P2C(1)                                                                  P2C(1)



NNAAMMEE
       p2c − Pascal to C translator, version 1.21alpha‐07.Dec.93

SSYYNNOOPPSSIISS
       pp22cc [ options ] [ file [ module ] ]

DDEESSCCRRIIPPTTIIOONN
       _P_2_c  is  a tool for translating Pascal programs into C.  The input con‐
       sists of a set of source files in any of the following Pascal dialects:
       HP Pascal, Turbo/UCSD Pascal, DEC VAX Pascal, Oregon Software Pascal/2,
       Macintosh Programmer’s  Workshop  Pascal,  Sun/Berkeley  Pascal,  Texas
       Instruments Pascal, Apollo Domain Pascal.  Modula‐2 syntax is also sup‐
       ported.  Output is a set of ..cc and ..hh 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 mod‐
       ifications, although _p_2_c sometimes chooses to generate readable code at
       the expense of absolute generality.  _P_2_c 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 pro‐
       gram.  In a pinch, _p_2_c will also serve as an ad  hoc  Pascal  compiler.
       The pp22cccc(1) script makes it easy to use _p_2_c as a compiler.

       Code generated by _p_2_c normally does not assume characters are signed or
       unsigned.  Also, it assumes iinntt is the same as either sshhoorrtt or lloonngg but
       does  not  depend on which.  However, if iinntt is not the same as lloonngg it
       is best to use a modern C compiler which supports  prototypes.   Gener‐
       ated  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 _<_p_2_c_/_p_2_c_._h_> which in turn includes
       _<_s_t_d_i_o_._h_> and various other common resources.   Also,  many  translated
       programs  will  need  to be linked with the run‐time library, typically
       _‐_l_p_2_c_.

       Given a file name, _p_2_c reads from the specified file and outputs  to  a
       file with a ..cc suffix added or substituted.  For example,

            p2c myfile.pas

       reads from _m_y_f_i_l_e_._p_a_s to produce the file _m_y_f_i_l_e_._c_.  The input file may
       contain a Pascal main program or a single Pascal module (or  "unit"  in
       Turbo and UCSD Pascal nomenclature), or it may just contain a number of
       procedures and declarations.  _P_2_c is designed to work for correct input
       programs.   That  is, it will accept partial programs but may occasion‐
       ally core dump if the input refers to undefined symbols.

       If the input is a module, the translator will also produce a file  _m_o_d_‐
       _u_l_e..hh  containing a translation of the module’s interface section.  The
       implementation section may be omitted in which case only  the  ..hh  file
       will be interesting.  If the program or module has include files, these
       may cause additional ..cc files to be generated depending on the value of
       the EExxppaannddIInncclluuddeess option (see below).

       If  no file name is given, _p_2_c reads Pascal from the standard input and
       writes the resulting C to standard output (though a ..hh 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  trans‐
       lated; any others are skipped.  The output files will be named _m_o_d_u_l_e..cc
       and _m_o_d_u_l_e..hh_.  _P_2_c never translates more than one module per run.

       Before        starting,        _p_2_c        reads        the         file
       _/_U_s_e_r_s_/_s_c_h_n_e_i_d_t_/_n_o_w_/_p_2_c_/_t_e_s_t_/_p_2_c_‐_1_._2_1_a_l_p_h_a_2_/_h_o_m_e_/_p_2_c_r_c  for a number of
       configuration parameters.  (The actual path used  on  your  system  may
       vary.   The  −−ii  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 IInncclluuddee %%HH//pp22ccrrcc
       to include the system file.  Next, _p_2_c attempts to read the file  _p_2_c_r_c
       in  your  directory  for  further configuration.  If this file does not
       exist, _p_2_c looks for _._p_2_c_r_c instead.

OOPPTTIIOONNSS
       −−oo _c_f_i_l_e
              Use _c_f_i_l_e in place of _f_i_l_e..cc or _m_o_d_u_l_e..cc as the  primary  output
              file.   A  single  dash (‘−o −’) says to write the C code to the
              standard output.

       −−hh _h_f_i_l_e
              Use _h_f_i_l_e in place of _m_o_d_u_l_e..hh as the output file for  interface
              text.   This only has effect if the input is an HP Pascal module
              or a Turbo Pascal unit.

       −−ss _s_f_i_l_e
              Read interface text from _s_f_i_l_e before beginning the translation.
              This  file  typically  contains  one or more modules, often with
              implementation sections omitted for speed, which the program  or
              module being translated will use.  (Typically the IImmppoorrttFFrroomm and
              IImmppoorrttDDiirr parameters in _p_2_c_r_c are set up to allow _p_2_c to  locate
              interface  text  without  needing any −−ss options.)  If there are
              several −−ss options in the command, the _s_f_i_l_e_s are read from left
              to right.

       −−pp_n    Display  progress  of  translation  in  the  form of a line num‐
              ber/file name display.  This is refreshed every _n lines,  25  by
              default.

       −−cc _r_c_f_i_l_e
              Read  local  configuration commands from _r_c_f_i_l_e instead of _p_2_c_r_c
              or _._p_2_c_r_c_.  A dash (‘−c −’) in place of _r_c_f_i_l_e causes  no  local
              configuration file to be used.

       −−vv     ("Vanilla.")   Do  not  read  from the system configuration file
              _/_U_s_e_r_s_/_s_c_h_n_e_i_d_t_/_n_o_w_/_p_2_c_/_t_e_s_t_/_p_2_c_‐_1_._2_1_a_l_p_h_a_2_/_h_o_m_e_/_p_2_c_r_c_.    Since
              some  of  the  parameters  in this file are required, your local
              configuration file must include those parameters instead.   This
              also  suppresses  the  file named by the P2CRC environment vari‐
              able.

       −−HH _h_o_m_e_d_i_r
              Use               _h_o_m_e_d_i_r               instead               of
              _/_U_s_e_r_s_/_s_c_h_n_e_i_d_t_/_n_o_w_/_p_2_c_/_t_e_s_t_/_p_2_c_‐_1_._2_1_a_l_p_h_a_2_/_h_o_m_e as the _p_2_c home
              directory.  The system _p_2_c_r_c file will be searched for  in  this
              directory.

       −−II_p_a_t_t_e_r_n
              Add  _p_a_t_t_e_r_n to the IImmppoorrttDDiirr search list of places to find mod‐
              ules 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, ....//%%ss..ppaass
              looks for _m_o_d_u_l_e_n_a_m_e..ppaass in the parent of the current directory.

       −−ii     This special option (which must be the only argument on the com‐
              mand  line  if used) simply copies the system configuration file
              _/_U_s_e_r_s_/_s_c_h_n_e_i_d_t_/_n_o_w_/_p_2_c_/_t_e_s_t_/_p_2_c_‐_1_._2_1_a_l_p_h_a_2_/_h_o_m_e_/_p_2_c_r_c  to   the
              standard  output  in its entirety.  (It may be used with −−HH, but
              −−ii is most useful precisely when you don’t know the location  of
              the home directory.)

       −−qq     Quiet  mode.  Suppresses output of status messages during trans‐
              lation.

       −−EE_n    Abort translation after _n errors.  If _n is omitted  it  defaults
              to  zero,  which means unlimited errors are allowed.  Use ‐‐EE11 to
              make _p_2_c halt after the first error.

       −−ee     Echo the Pascal source  into  the  output  file,  surrounded  by
              #ifdefs.   This  is  the same as the CCooppyySSoouurrccee parameter in the
              _p_2_c_r_c file.

       −−aa     Produce modern ANSI C.  This is a convenient  override  for  the
              AAnnssiiCC parameter in the _p_2_c_r_c file.

       −−LL _l_a_n_g_u_a_g_e
              Select  input  language  name,  such as VAX or TURBO.  This is a
              convenient override for the LLaanngguuaaggee parameter.

       −−VV     Verbose mode.  This causes _p_2_c to generate an additional  ".log"
              file  with further details of the translation, such as a list of
              warnings and notes including those which are suppressed  in  the
              regular output.

       −−ccoommpp  Compiler  mode.  This switch tells _p_2_c to use various configura‐
              tion defaults that are more suitable for use as  a  Pascal  com‐
              piler  rather  than  a translator.  It is the same as specifying
              the following options in your _p_2_c_r_c file:

                   ElimDeadCode 0
                   AnalyzeFlow 0
                   MaxLineBreakTies 0
                   FoldConstants 1
                   FoldStrConstants 1
                   OffsetForLoops 0
                   StaticLinks 1
                   BitwiseMod 0
                   BitwiseDiv 0
                   AssumeBits 0
                   AssumeSigns 0
                   FormatStrings 1
                   StructFiles 1
                   FullStrWrite 1

              The _p_2_c_c script specifies this option when it runs _p_2_c  to  com‐
              pile a Pascal program.

       −−llooccaall Local settings.  This switch uses various configuration defaults
              that are appropriate if the code generated by _p_2_c is going to be
              compiled and run on the same machine that ran _p_2_c itself.

       −−cchheecckk Enable  all error checking.  Normally, some error checks are off
              by default, as described in the comments  in  the  system  _p_2_c_r_c
              file.

       −−MM00    Disable  memory  conservation.   This  prevents _p_2_c from freeing
              various data structures after translating each function, in case
              this new conservation feature causes unforseen problems.

       −−RR     Regression  testing mode.  Formats notes and warning messages in
              a way that makes it easier to run _d_i_f_f(1) on the output of  _p_2_c_.

       _P_2_c  also understands a few debugging options which may occasionally be
       useful when tracking down translation problems.  The  −−dd_n  option  sets
       the "debug level" to _n_, a small integer which is normally zero.  Debug‐
       ging output is written into the regular output file along  with  the  C
       code; the higher your _n_, the more "wallpaper" you get.  Also, −−tt prints
       debugging information at every Pascal token, −−BB_n  enables  line‐breaker
       debugging,  −−CC_n  enables  comment  placement debugging, and −−FF_n enables
       flow‐analysis debugging.

CCHHOOIICCEE OOFF SSOOUURRCCEE LLAANNGGUUAAGGEE
       The LLaanngguuaaggee configuration parameter or −−LL  command‐line  option  tells
       _p_2_c  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  LLaanngguuaaggee  parameter 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 parame‐
       ters as described below.

       The following language words are supported by  _p_2_c_.   Names  are  case‐
       insensitive.

       HHPP      HP  Pascal.   This is the default language.  All features of HP
               Standard Pascal, the Pascal Workstation version, are  supported
               except  as  noted in BUGS below.  Some features of MODCAL, HP’s
               extended Pascal, are also supported.  This is a superset of ISO
               standard  Pascal,  including  conformant  arrays and procedural
               parameters.

       HHPP‐‐UUXX   HP  Pascal,  HP‐UX  version.   Almost  identical  to  the  "HP"
               dialect.

       TTuurrbboo   Turbo Pascal 5.0 for the IBM PC.  Few conflicts with HP Pascal,
               so the LLaanngguuaaggee parameter is not often needed for Turbo.  (Most
               important  is  that the Turbo and HP dialects use 16 and 32 bit
               integers, respectively.)

       UUCCSSDD    UCSD Pascal.  Similar to Turbo in many ways.

       MMPPWW     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  cchhaarr  variables  are
               sometimes stored in 16 bits.

       VVAAXX     VAX/VMS Pascal version 3.5.  Most but not all language features
               supported.  This has not yet been tested on large programs.

       OOrreeggoonn  Oregon Software Pascal/2.  All features implemented.

       BBeerrkk    Berkeley Pascal with Sun extensions.

       TTIIPP     Texas Instruments Pascal.

       AAppoolllloo  Apollo Domain Pascal.

       MMoodduullaa  Modula‐2.  Based on Wirth’s _P_r_o_g_r_a_m_m_i_n_g _i_n _M_o_d_u_l_a_‐_2_,  3rd  edi‐
               tion.    Proper  setting  of  the  LLaanngguuaaggee  parameter  is  _n_o_t
               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 _f_o_o_._d_e_f (definition part) and _f_o_o_._m_o_d  (imple‐
               mentation  part)  for  module  _f_o_o_.  Then a pattern like %%ss..ddeeff
               must be included in the IImmppoorrttDDiirr list, and LLiibbrraarryyFFiillee must be
               changed to refer to _s_y_s_t_e_m_._m_2 instead of _s_y_s_t_e_m_._i_m_p_.  To trans‐
               late the definition part, give the command

                    p2c foo.def

               to translate the definition part into files  _f_o_o_._h  and  _f_o_o_._c;
               the latter will usually be empty.  The command

                    p2c ‐s foo.def foo.mod

               will translate the implementation part into file _f_o_o_._c_.

       Even  if all language features are supported for a dialect, some prede‐
       fined 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.

CCOONNFFIIGGUURRAATTIIOONN PPAARRAAMMEETTEERRSS
       _P_2_c is highly configurable.  The defaults are suitable for most  appli‐
       cations,  but  customizing  these parameters will help you get the best
       possible translation.  Since the output of _p_2_c 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 _p_2_c to generate more correct, effi‐
       cient, or readable code.

       The _p_2_c_r_c files contain a list of parameters, one per line.  The system
       configuration  file,  which  may  be viewed using the −−ii option to _p_2_c_,
       serves as an example of the proper format.  Parameter names  are  case‐
       insensitive.   If  a  parameter  name occurs exactly once in the system
       _p_2_c_r_c_, 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  con‐
       figuration line adds an entry.

       Many  _p_2_c_r_c options take a numeric value of 0 or 1, roughly correspond‐
       ing to "no" or "yes."  Sometimes a blank value or the value "ddeeff"  cor‐
       responds  to an intermediate "maybe" state.  For example, the stylistic
       option EExxttrraaPPaarreennss switches between copious or minimal  parentheses  in
       expressions,  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  aanndd and oorr expressions, adds
       "_f_r_e_d" to the list of names to avoid using in  generated  C  code,  and
       defines  a  special translation for the Pascal program’s _s_l_o_p_e function
       using the standard C _a_t_a_n_2 function and a  constant  _R_a_d_D_e_g  presumably
       defined  in the program.  Whitespace is generally not allowed in embed‐
       ded parameters.  The ‘=’ sign  is  required  for  embedded  parameters,
       though it is optional in _p_2_c_r_c files.  Comments within embedded parame‐
       ters are delimited by ‘##’.  Numeric parameters may  replace  ‘=’  with
       ‘+’ or ‘‐’ to increase or decrease 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}
            _s_o_m_e _d_e_c_l_a_r_a_t_i_o_n_s
            {VarFiles    ## Back to original FILE * passing}

       causes the parameter VVaarrFFiilleess to have the value 0 for those few  decla‐
       rations, 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 pre‐
       ceded  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 _s_t_r_i_n_g_s module’s include file  for  the
       rest  of  the  translation, but the assignment of EExxppoorrttSSyymmbbooll pertains
       only to the module itself.

       For the complete list of _p_2_c_r_c parameters, run _p_2_c with the −−ii  option.
       Here are some additional comments on selected parameters:

       IImmppoorrttAAllll      Because  Turbo  Pascal  only  allows one unit per source
                      file, _p_2_c normally stops reading past the word _i_m_p_l_e_m_e_n_‐
                      _t_a_t_i_o_n  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 IImmppoorrttAAllll option lets you
                      override the default behavior for your Pascal dialect.

       AAnnssiiCC          This parameter selects which dialect of C to use.  If 1,
                      all  conventions  of  ANSI  C such as prototypes, vvooiidd **
                      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 eennuumm and vvooiidd but not vvooiidd **  or
                      prototypes.   Once  again  there  are  a number of other
                      parameters which may be used to control  the  individual
                      features if just setting AAnnssiiCC is not enough.

       CC++++            This  tells  _p_2_c  to use a number of language extensions
                      present in C++:  Specifically, it enables the "//"  for‐
                      mat  for comments, use of "anonymous unions" for variant
                      records, use of declarations within the  function  body,
                      use  of  references for VAR parameters, and use of "new"
                      and "delete" instead of "malloc" and "free".   _P_2_c  will
                      check  for collisions with C++ reserved words unless you
                      explicitly set the C++ option to zero.

       TTuurrbbooOObbjjeeccttss   _P_2_c recognizes two  major  dialects  of  object‐oriented
                      Pascal.   Turbo Pascal 6.0 oobbjjeecctt types translate fairly
                      directly into C++ classes.  In  Apple’s  Object  Pascal,
                      the oobbjjeecctt type has similar syntax but represents a han‐
                      dle (a double pointer)  to  an  object  rather  than  an
                      object  itself.   The TTuurrbbooOObbjjeeccttss option (whose default
                      is determined by  the  LLaanngguuaaggee  setting)  says  whether
                      objects  should  be direct or indirect through pointers.
                      (_P_2_c uses pointers instead of handles; _p_2_c is most often
                      used  to  make  programs  more portable, and few systems
                      except the Mac use handles in this way.)

       UUsseeVVEExxtteerrnn     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  oth‐
                      ers  must  declare  "extern int foo;".  _P_2_c accomplishes
                      this by declaring public variables "vveexxtteerrnn"  in  header
                      files,  and arranging for the macro vveexxtteerrnn to expand to
                      eexxtteerrnn or to  nothing  when  appropriate.   If  you  set
                      UUsseeVVEExxtteerrnn=0  _p_2_c  will  instead  declare variables in a
                      simpler way that works only on UNIX‐style linkers.

       UUsseeAAnnyyppttrrMMaaccrrooss
                      Certain C reserved words have meanings  which  may  vary
                      from  one C implementation to another.  _P_2_c uses special
                      capitalized names  for  these  words;  these  names  are
                      defined as macros in the file _p_2_c_._h which all translated
                      programs include.  You can set UUsseeAAnnyyppttrrMMaaccrrooss=0 to dis‐
                      able  the  use of these macros.  Note that the functions
                      of many of these macros can also be had  directly  using
                      other  parameters;  for example, UUsseeCCoonnssttss allows you to
                      specify whether your target language recognizes the word
                      ccoonnsstt  in  constant declarations.  The default is to use
                      the CCoonnsstt macro instead, so that your code will be  por‐
                      table to either kind of implementation.

                      SSiiggnneedd  expands to the reserved word ssiiggnneedd if that word
                      is available, otherwise it is given a  null  definition.
                      Similarly,  CCoonnsstt  expands  to  ccoonnsstt if that feature is
                      available.  The words VVoollaattiillee  and  RReeggiisstteerr  are  also
                      defined  in  _p_2_c_._h_,  although  _p_2_c  does not use them at
                      present.  The word CChhaarr expands to cchhaarr by default,  but
                      might  need  to  be redefined to ssiiggnneedd cchhaarr or uunnssiiggnneedd
                      cchhaarr in a particular implementation.  This is  used  for
                      the  Pascal  character type; lowercase cchhaarr is used when
                      the desired meaning is "byte," not "character."

                      The word SSttaattiicc always expands  to  ssttaattiicc  by  default.
                      This  is used in situations where a function or variable
                      is declared static to make it local to the source  file;
                      lowercase  ssttaattiicc  is  used  for static local variables.
                      Thus you can redefine SSttaattiicc to be null if you  want  to
                      force  private names to be public for purposes of debug‐
                      ging.

                      The word VVooiidd expands to vvooiidd in all cases; it  is  used
                      when  declaring  a  function  with no return value.  The
                      word AAnnyyppttrr is a typedef for vvooiidd ** or cchhaarr ** as  neces‐
                      sary; it represents a generic pointer.

       UUsseePPPPMMaaccrrooss    The  _p_2_c_._h  header also declares two macros for function
                      prototyping, PPPP(x) and PPVV().  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  supported,  you
                      instead get

                           Void foo  ();
                           Char *bar ();

                      By  default, _p_2_c uses these macros for all function dec‐
                      larations, but function _d_e_f_i_n_i_t_i_o_n_s are written in  old‐
                      style  C.   The UUsseePPPPMMaaccrrooss parameter can be set to 0 to
                      disable all use of PPPP and PPVV, or it can be set to  1  to
                      use  the macros even when defining a function.  (This is
                      accomplished by preceding each old‐style definition with
                      a  PPPP‐style  declaration.)   If  you know your code will
                      always be compiled on systems that support  prototyping,
                      it  is prettier to set PPrroottoottyyppeess=1 or simply AAnnssiiCC=1 to
                      get true function prototypes.

       EEaattNNootteess       Notes and  warning  messages  containing  any  of  these
                      strings  as  sub‐strings  are not emitted.  Each type of
                      message includes an identifier like [[114455]]; you  can  add
                      this  identifier  to  the EEaattNNootteess 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 space‐separated  list,  and
                      thus may not contain embedded spaces.  To suppress notes
                      around a section of code,  use,  e.g.,  _{_E_a_t_N_o_t_e_s_+_[_1_4_5_]_}
                      and  _{_E_a_t_N_o_t_e_s_‐_[_1_4_5_]_}_.   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.

       EExxppaannddIInncclluuddeess 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  EExxppaannddIInncclluuddeess=0,
                      _p_2_c  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 messages, don’t use this option.  By  com‐
                      bining  this  option  with SSttaattiiccFFuunnccttiioonnss=0, then doing
                      some fairly minor editing on the result, you can convert
                      a  pseudo‐modular  Pascal  program  into a truly modular
                      collection of C source files.

       EElliimmDDeeaaddCCooddee   Some transformations that _p_2_c does on  the  program  may
                      result  in  unreachable  or "dead" code.  By default _p_2_c
                      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 EElliimmDDeeaaddCCooddee=0.

       AAnnaallyyzzeeFFllooww    By default _p_2_c does some basic dataflow analysis on  the
                      program in an attempt to locate code that can be simpli‐
                      fied due to knowledge about the possible values of  cer‐
                      tain variables.  For example, a Pascal rreewwrriittee statement
                      must translate to an iiff that either  calls  ffooppeenn  on  a
                      formerly closed file variable, or ffrreeooppeenn on an already‐
                      open file.  If flow analysis can prove that the file was
                      open  or  closed  upon  entry  to  the statement, a much
                      cleaner translation is possible.

                      It is possible that flow analysis will make  simplifica‐
                      tions  that  are  undesirable or buggy.  If this occurs,
                      you can set AAnnaallyyzzeeFFllooww to 0 to disable this feature.

       SSkkiippIInnddiicceess    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  references  like "a[i]" changed to "a[i‐2]" every‐
                      where.  If SSkkiippIInnddiicceess is set to a value of 2 or higher,
                      this array would instead be translated to a[11] with the
                      first two elements never  used.   This  arrangement  may
                      generate  incorrect code, though, for tricky source pro‐
                      grams.

       FFoollddCCoonnssttaannttss  Pascal non‐structured constants generally  translate  to
                      ##ddeeffiinnee’s in C.  Set this to 1 to have constants instan‐
                      tiated directly into the code.  This may be turned on or
                      off  around specific constant declarations.  Set this to
                      0 to force _p_2_c to make absolutely no  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 _p_2_c to
                      take advantage of its knowledge of a  constant’s  value,
                      such  as by generating code that assumes the constant is
                      positive.

       CChhaarrCCoonnssttss     This governs whether single‐character string literals in
                      Pascal ccoonnsstt declarations should be interpreted as char‐
                      acters or strings.  In other words,  _c_o_n_s_t  _a_=_’_x_’_;  will
                      translate   to   _#_d_e_f_i_n_e  _a  _’_x_’  if  CChhaarrCCoonnssttss=1  (the
                      default), or to _#_d_e_f_i_n_e _a _x if CChhaarrCCoonnssttss=0.  Note  that
                      if  _p_2_c  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, _p_2_c will have to write char‐to‐string conversion
                      code each time the constant is used.

       PPrreesseerrvveeTTyyppeess  _P_2_c  makes  an attempt to retain the original names used
                      for data types.  For example,

                           type foo = integer; bar = integer;

                      establishes two synonyms for the standard integer  type;
                      _p_2_c  does  its  best  to preserve the particular synonym
                      that was used to declare each integer variable.  Because
                      the Pascal language treats these types as indistinguish‐
                      able, there will be cases in the translation  where  _p_2_c
                      must  fall  back on the "true" type, iinntt.  PPrreesseerrvveeTTyyppeess
                      and a few related options control whether various  kinds
                      of  type names are preserved.  The default settings pre‐
                      serve all type names except for pointer types, which use
                      "*"  notation  throught  the program.  This reflects the
                      fact that Pascal forces pointer types to be  named  when
                      traditionally they are not separately named in C.

       VVaarrSSttrriinnggss     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
                      _s_t_r_m_a_x function.  You can prevent _p_2_c  from  creating  a
                      hidden  size  parameter  by setting VVaarrSSttrriinnggss=0.  (Note
                      that each function uses the value of  VVaarrSSttrriinnggss  as  of
                      the  _f_i_r_s_t  declaration  of the function that is parsed,
                      which is often in the interface section of a module.)

       PPrroottoottyyppeess     Control whether ANSI C  function  prototypes  are  used.
                      Default  is  according  to AAnnssiiCC or CC++++.  This also con‐
                      trols whether to include parameter names or  just  their
                      types in situations where names are optional.  The FFuullll‐‐
                      PPrroottoottyyppiinngg parameter allows prototypes to be  generated
                      for declarations but not for definitions (older versions
                      of Lightspeed C required this).  If you use a mixture of
                      prototypes  and  old‐style definitions, types like short
                      and float will be promoted to int and double as required
                      by  the  ANSI  standard,  unless  PPrroommootteeAArrggss is used to
                      override this.  The CCaassttAArrggss parameter controls  whether
                      type‐casts  are  used  in function arguments; by default
                      they are used only if prototypes are not available.

       SSttaattiiccLLiinnkkss    HP Pascal and Turbo Pascal each include the  concept  of
                      procedure  or  function  pointers,  though with somewhat
                      different  syntaxes.   _P_2_c  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 ssttrruucctt  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 notation can
                      be forced  by  setting  SSttaattiiccLLiinnkkss=1.   In  Turbo,  the
                      default  (SSttaattiiccLLiinnkkss=0)  is  to  use  plain  C function
                      pointers with no static links.  A third  option  (SSttaattii‐‐
                      ccLLiinnkkss=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 global).

       SSmmaallllSSeettCCoonnsstt  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 single integer variable using bit operations.  (The
                      SSeettBBiittss parameter may be used to change the upper  limit
                      of  31.)   The  SSmmaallllSSeettCCoonnsstt 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 lloonngg 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 normalized so that _s[_s[0]]
                      is nonzero for any nonempty set.  The standard  run‐time
                      library  includes all the necessary procedures for oper‐
                      ating on sets.

       RReettuurrnnVVaalluueeNNaammee
                      This is one of  many  "naming  conventions"  parameters.
                      Most of these take the form of a _p_r_i_n_t_f‐like string con‐
                      taining a _%_s where the relevant information  should  go.
                      In the case of RReettuurrnnVVaalluueeNNaammee, 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
                      assignments  to its return value buried within the body,
                      so that _r_e_t_u_r_n statements cannot conveniently  be  used.
                      Some   parameters   (RReettuurrnnVVaalluueeNNaammee  included)  do  not
                      require the _%_s to be present in the format  string;  for
                      example, the standard _p_2_c_r_c file stores every function’s
                      return value in a variable called _R_e_s_u_l_t_.

       AAlltteerrnnaatteeNNaammee  _P_2_c normally translates Pascal names into C names verba‐
                      tim,  but  occasionally  this is not possible.  A Pascal
                      name may be a C reserved word or traditional C name like
                      _p_u_t_c_, or there may be several like‐named things that are
                      hidden from each other by  Pascal’s  scoping  rules  but
                      must  be  global in C.  In these situations _p_2_c uses the
                      parameter AAlltteerrnnaatteeNNaammee11 to generate an alternative name
                      for  the symbol.  The default is to add an underscore to
                      the name.  There is also an AAlltteerrnnaatteeNNaammee22 parameter for
                      a  second alternate name, and an AAlltteerrnnaatteeNNaammee parameter
                      for the _nth alternate name.  (The value for this parame‐
                      ter should include both a _%_s and a _%_d_, in either order.)
                      If these latter parameters are not defined, _p_2_c  applies
                      AAlltteerrnnaatteeNNaammee11 many times over.

       EExxppoorrttSSyymmbbooll   Symbols in the interface section for a Pascal module are
                      formatted according to the  value  of  EExxppoorrttSSyymmbbooll,  if
                      any.   It  is not uncommon to use _m_o_d_u_l_e_n_a_m_e___%_s for this
                      symbol; the default is _%_s_, i.e.,  no  special  treatment
                      for   exported   symbols.    If   you  also  define  the
                      EExxppoorrtt__SSyymmbbooll 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.

       AAlliiaass          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).

       SSyynnoonnyymm        This creates a synonym for another Pascal symbol or key‐
                      word.  The format is

                           SSyynnoonnyymm _o_l_d_‐_n_a_m_e _= _n_e_w_‐_n_a_m_e

                      All occurrences  of  _o_l_d_‐_n_a_m_e  in  the  input  text  are
                      treated as if they were _n_e_w_‐_n_a_m_e by the parser.  If _n_e_w_‐
                      _n_a_m_e is a keyword, _o_l_d_‐_n_a_m_e will be an  equivalent  key‐
                      word.  If _n_e_w_‐_n_a_m_e is the name of a predefined function,
                      _o_l_d_‐_n_a_m_e will behave in the same way as  that  function,
                      and  so on.  If _n_e_w_‐_n_a_m_e is omitted, then occurrences of
                      _o_l_d_‐_n_a_m_e are entirely ignored in the input  file.   Syn‐
                      onyms  allow  you to skip over a keyword in your dialect
                      of Pascal that is not understood by _p_2_c_, or to  simulate
                      a  keyword or predefined identifier of your dialect with
                      a similar one that _p_2_c recognizes.  Note that all prede‐
                      fined  functions are available at all times; if you have
                      a library routine that behaves like,  e.g.,  Turbo  Pas‐
                      cal’s _g_e_t_m_e_m procedure, you can make your routine a syn‐
                      onym for _g_e_t_m_e_m even if you are not translating in Turbo
                      mode.

       NNaammeeOOff         This defines the name to use in C for a specific symbol.
                      It must appear before the symbol is declared in the Pas‐
                      cal  code;  it is usually placed in the local _p_2_c_r_c file
                      for the project.  The format is

                           NNaammeeOOff _p_a_s_c_a_l_‐_n_a_m_e _= _C_‐_n_a_m_e

                      By default, Pascal names map directly onto C names  with
                      no  change  (except  for the various kinds of formatting
                      outlined above).  If the _p_a_s_c_a_l_‐_n_a_m_e is of the form _m_o_d_‐
                      _u_l_e_._n_a_m_e or _p_r_o_c_e_d_u_r_e_._n_a_m_e then the command applies only
                      to the instance of the Pascal name  that  is  global  to
                      that  module, or local to that procedure.  Otherwise, it
                      applies to all usages of the name.

       VVaarrMMaaccrroo       This is analogous to NNaammeeOOff, but  specifically  for  use
                      with  Pascal  variables.  The righthand side can be most
                      any C expression; all references  to  the  variable  are
                      expanded  into  that  C expression.  Names used in the C
                      expression are taken verbatim.  There is also  a  CCoonnsstt‐‐
                      MMaaccrroo  parameter  for translating constants as arbitrary
                      expressions.  Note that the  variable  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 Pas‐
                      cal‐name appears in  the  expression:   If  you  ask  to
                      replace  _i  with  _i_+_1_,  the  variable  _i  will  still be
                      declared but its  value  will  be  shifted  accordingly.
                      Note  that  if  _i  appears  on  the  lefthand side of an
                      assignment, _p_2_c will use algebra to "solve" for _i_.

                      In all cases where _p_2_c parses C expressions, all C oper‐
                      ators  are  recognized  except compound assignments like
                      ‘+=’.  (Increment and decrement operators are  allowed.)
                      All  variable  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 introduced; it has the same precedence  as  ‘.’  or
                      ‘‐>’  but the righthand side must be a Pascal type iden‐
                      tifier (built‐in or defined by your  program  previously
                      to  when  the  macro definition was parsed), or an arbi‐
                      trary Pascal type expression in parentheses.  The  left‐
                      hand  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 _w_r_i_t_e_l_n).

       FFiieellddMMaaccrroo     Here the lefthand side must have the form  _r_e_c_o_r_d_._f_i_e_l_d_,
                      where  _r_e_c_o_r_d  is the Pascal type or variable name for a
                      record, and _f_i_e_l_d is a field in that record.  The right‐
                      hand side must be a C expression generally including the
                      name _r_e_c_o_r_d_.  All instances of that name are replaced by
                      the actual record being "dotted."  For example,

                           FieldMacro Rect.topLeft = topLeft(Rect)

                      translates  _a_[_i_]_._t_o_p_L_e_f_t  into _t_o_p_L_e_f_t_(_a_[_i_]_)_, where _a is
                      an array of _R_e_c_t_.

       FFuunnccMMaaccrroo      The lefthand side must be any Pascal function or  proce‐
                      dure  name plus a parameter list.  The number of parame‐
                      ters must match the number in the  function’s  uses  and
                      declaration.   Calls to the function are replaced by the
                      C expression on the righthand side.  For example,

                           FuncMacro PtInRect(p,r) = PtInRect(p,&r)

                      causes the second argument of _P_t_I_n_R_e_c_t to be  passed  by
                      reference,  even  though  the declaration says it’s not.
                      If the function in question is actually defined  in  the
                      program  or  module being translated, the FFuunnccMMaaccrroo will
                      not affect the definition but it will affect  all  calls
                      to the function elsewhere in the module.  FFuunnccMMaaccrrooss can
                      also be applied to  predefined  or  never‐defined  func‐
                      tions.

       RReeppllaacceeBBeeffoorree  This option specifies a string replacement to be done on
                      every Pascal source line.  For example:

                           ReplaceBefore     "{$ifdef"     "{EMBED     #ifdef"
                           ReplaceBefore "{$endif}" "{EMBED #endif}"

                      These lines rewrite Turbo Pascal compile‐time condition‐
                      als into comments beginning with the special word EMBED.
                      This  word  instructs p2c to format the rest of the com‐
                      ment without "/* */" delimiters, i.e., the rest  of  the
                      comment  is  embedded  directly in the output C program.
                      There is also a  RReeppllaacceeAAfftteerr  option,  which  specifies
                      replacements to be done on the output of _p_2_c_.

                      Currently,   this  feature  makes  only  literal  string
                      replacements, not pattern‐based matches.  Some users  of
                      _p_2_c  have  found it useful to feed their Pascal programs
                      through a more powerful editor like _s_e_d or  _p_e_r_l  before
                      giving  them  to  _p_2_c_.   Quite often this is all that is
                      necessary to get an acceptable translation in  the  face
                      of unrecognized Pascal dialects or language features.

       IInncclluuddeeFFrroomm    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 gener‐
                      ated for the module.

       IImmppoorrttFFrroomm     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 IImmppoorrttFFrroomm entry is found for
                      a module, the path defined  by  the  IImmppoorrttDDiirr  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_._p_a_s and _%_s_._t_e_x_t in the current direc‐
                      tory,                      then                      for
                      _/_U_s_e_r_s_/_s_c_h_n_e_i_d_t_/_n_o_w_/_p_2_c_/_t_e_s_t_/_p_2_c_‐_1_._2_1_a_l_p_h_a_2_/_h_o_m_e_/_%_s_._i_m_p_.
                      (where  /Users/schneidt/now/p2c/test/p2c‐1.21alpha2/home
                      is the _p_2_c home directory.)

       SSttrruuccttFFuunnccttiioonn This  parameter  is a list of functions which follow the
                      _p_2_c 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 function _s_t_r_c_p_y is an example  of  this  con‐
                      cept.   _S_p_r_i_n_t_f  also behaves this way in some dialects;
                      it always appears on the SSttrruuccttFFuunnccttiioonn list  regardless
                      of  the  type of implementation.)  The system configura‐
                      tion file includes a list of common structured functions
                      so  that  _p_2_c’s  optimizer  will  know how to manipulate
                      them.

       SSttrrllaappFFuunnccttiioonn Functions on  this  list  are  structured  functions  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.

       DDeetteerrmmiinniissttiicc  Functions  on  this  list  have  no side effects or side
                      dependencies.  An example is the  _s_i_n  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.  _P_2_c can make use of this
                      knowledge when optimizing code for efficiency  or  read‐
                      ability.   Functions on this list are also assumed to be
                      relatively fast, so that it is acceptable to duplicate a
                      call to the function.

       LLeeaavveeAAlloonnee     Functions  on  this list are not subjected to the normal
                      built‐in translation rules that _p_2_c would otherwise use.
                      For example, adding _w_r_i_t_e_l_n to this list would translate
                      _w_r_i_t_e_l_n statements blindly into calls to a  C  _w_r_i_t_e_l_n_(_)
                      function,  rather  than being translated into equivalent
                      _p_r_i_n_t_f calls.  The built‐in  translation  is  also  sup‐
                      pressed if the function has a FFuunnccMMaaccrroo.

       BBuuffffeerreeddFFiillee   _P_2_c  normally  assumes binary files will use _r_e_a_d_/_w_r_i_t_e_,
                      not _g_e_t_/_p_u_t_/_^ 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 BBuuffffeerreeddFFiillee
                      to  force  _p_2_c  to allocate buffers for them; do this if
                      you get a warning message that  says  it  is  necessary.
                      Set  BBuuffffeerreeddFFiillee=1  to  buffer all files, in which case
                      UUnnBBuuffffeerreeddFFiillee allows you to force certain files _n_o_t  to
                      have buffers.

       SSttrruuccttFFiilleess    If  _p_2_c  still can’t translate your file operations cor‐
                      rectly, you can set SSttrruuccttFFiilleess=1 to cause Pascal  files
                      to translate into structs which include the usual C _F_I_L_E
                      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 _p_2_c to do  a  cor‐
                      rect translation in many more cases.

       CChheecckkFFiilleeEEOOFF   Normally  only  file‐open  operations  are  checked  for
                      errors.  Additional error checking, such  as  read‐past‐
                      end‐of‐file,  can be enabled with parameters like CChheecckk‐‐
                      FFiilleeEEOOFF.  These checks can make the code very ugly!   If
                      I/O  checking is enabled by the program ($$iioocchheecckk oonn$$ in
                      HP Pascal; {{$$II++}} in Turbo; this is  always  the  default
                      state),  these  checks will generate fatal errors unless
                      enclosed in an HP Pascal ttrryy‐rreeccoovveerr construct.  If  I/O
                      checking  is disabled, these will cause the global vari‐
                      able _P___i_o_r_e_s_u_l_t to be set zero or nonzero  according  to
                      the  outcome.   The default for most of these options is
                      to check only when I/O checking is enabled.

IISSSSUUEESS
       IInntteeggeerr ssiizzee..  _P_2_c 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 IInntt‐‐
       SSiizzee appropriately.  In particular  setting  IInnttSSiizzee=32  will  generate
       much cleaner code: _p_2_c no longer must carefully cast function arguments
       between int and long.  These casts also will  be  unnecessary  if  ANSI
       prototypes are available.  To disable int/long casting because you know
       at least one of these cases will hold, set CCaassttLLoonnggAArrggss=0.   (The  CCaass‐‐
       ttAArrggss  parameter  similarly  controls  other  types  of  casts, such as
       between ints and doubles.)  The IInntteeggeerr1166  parameter  controls  whether
       Pascal  integers  are  interpreted  as  16 or 32 bits, or translated as
       native C integers.  The default value depends on the LLaanngguuaaggee selected.

       SSiiggnneedd//uunnssiiggnneedd  cchhaarrss..  Pascal characters are normally "weakly" inter‐
       preted as unsigned; this is controlled by UUnnssiiggnneeddCChhaarr.  The default is
       "either,"  so that C’s native cchhaarr 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
       {{SSIIGGNNEEDD}} cchhaarr and {{UUNNSSIIGGNNEEDD}} cchhaarr in the few cases where it really mat‐
       ters.  These comments are controlled by the SSiiggnneeddCCoommmmeenntt and UUnnssiiggnneedd‐‐
       CCoommmmeenntt parameters.  (The type {{UUNNSSIIGGNNEEDD}} iinntteeggeerr is also  recognized.)
       The  SSiiggnneeddCChhaarr  parameter  tells  whether  C  characters are signed or
       unsigned (default is "unknown").   The  HHaassSSiiggnneeddCChhaarr  parameter  tells
       whether the phrase "signed char" is legal in the output.  If it is not,
       _p_2_c may have to translate Pascal signed bytes into C shorts.

       SSppeecciiaall ttyyppeess..  _P_2_c understands the following  predefined  Pascal  type
       names: iinntteeggeerr, signed integers depending on IInntteeggeerr1166; lloonnggiinntt, signed
       32‐bit integers; uunnssiiggnneedd,  unsigned  32‐bit  integers;  sswwoorrdd,  signed
       16‐bit integers; wwoorrdd, unsigned 16‐bit integers; cc__iinntt, signed native C
       integers; cc__uuiinntt, unsigned native C integers; ssbbyyttee, signed 8‐bit inte‐
       gers;  bbyyttee,  unsigned  8‐bit  integers;  rreeaall,  floating‐point numbers
       depending on DDoouubblleeRReeaallss; ssiinnggllee,  single‐precision  floats;  lloonnggrreeaall,
       ddoouubbllee,  and  eexxtteennddeedd,  double‐precision  floats;  ppooiinntteerr and aannyyppttrr,
       generic pointers (assignment‐compatible with any pointer type); ssttrriinngg,
       generic  string of length SSttrriinnggDDeeffaauulltt (normally 255); also, the usual
       Pascal types cchhaarr, bboooolleeaann, and tteexxtt.  (If your Pascal  uses  different
       names for these concepts, the SSyynnoonnyymm option will come in handy.)

       EEmmbbeeddddeedd  ccooddee..   It is possible to write a Pascal comment containing C
       code to be embedded into the output.  See the descriptions of EEmmbbeeddCCoomm‐‐
       mmeenntt  and its relatives in the system _p_2_c_r_c file.  These techniques are
       helpful if you plan to do repeated translations of code that  is  still
       being  maintained  in Pascal.  See the description of RReeppllaacceeBBeeffoorree for
       an example use of embedded code.

       CCoommmmeennttss aanndd bbllaannkk lliinneess..  _P_2_c collects the  comments  in  a  procedure
       into  a list.  All comments and statements are stamped with serial num‐
       bers which are used to reattach comments 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 _p_2_c will also reproduce your usage
       of  blank  lines.   If the comment mechanism goes awry, you can disable
       comments with EEaattCCoommmmeennttss or disable their being attached to code  with
       SSppiittCCoommmmeennttss.

       IInnddeennttaattiioonn..   _P_2_c  has a number of parameters to govern indentation of
       code.  The default values produce the GNU  Emacs  standard  indentation
       style,  although  _p_2_c can do a better job since it knows more about the
       code it is  indenting.   Indentation  works  by  applying  "indentation
       deltas," which are either absolute numbers (which override the previous
       indentation), or signed relative numbers (which  augment  the  previous
       indentation).  A delta of "+0" specifies no change in indentation.  All
       of the indentation options are described in the standard _p_2_c_r_c file.

       LLiinnee bbrreeaakkiinngg..  _P_2_c uses an algorithm similar to the  TeX  typesetter’s
       paragraph  formatter  for breaking long statements into multiple lines.
       A "penalty" is assigned to various 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 penalties  for
       overrunning  the  desired  maximum line length (default 78 columns), an
       infinite penalty for  overrunning  the  absolute  maximum  line  length
       (default 90), and progressively greater penalties for breaking at oper‐
       ators deeply nested in expressions.  Parameters such as  OOppBBrreeaakkPPeennaallttyy
       control  the  relative  weights of various choices.  BBrreeaakkAArriitthh and its
       neighbors control whether the operator at a line break should be placed
       at  the  end  of the previous line or at the beginning of the next.  If
       you don’t want any oversize lines, define MMaaxxLLiinneeWWiiddtthh=78.

       Unlike TeX, _p_2_c’s line breaker must actually try all possible  sets  of
       break  points.   To avoid excessive computation, the total penalty con‐
       tributed at each decision point must sum to a nonnegative value;  nega‐
       tive  values  are  clipped  up  to zero.  This allows _p_2_c to prune away
       obviously undesirable alternatives in advance.   The  MMaaxxLLiinneeBBrreeaakkTTrriieess
       parameter  (default  5000) controls how many alternatives to try before
       giving up and using the best so far.

       PPAASSCCAALL__MMAAIINN..  _P_2_c 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
       AArrggCCNNaammee to be _a_r_g_c_, AArrggVVNNaammee to be _a_r_g_v_, and MMaaiinnNNaammee (normally  "PAS‐
       CAL_MAIN")  to  be  blank.   This  will work if argc and argv are never
       accessed outside of your main program.

BBUUGGSS
       _P_2_c was designed with the idea that  clean,  readable  output  in  most
       cases  is  worth  more than guaranteed correct output in extreme cases.
       _P_2_c is _n_o_t a compiler!  However,  ideally  the  "extreme"  cases  would
       include  only  those which never arise in real life.  Thus if _p_2_c actu‐
       ally generates incorrect code I will consider it a bug, but I will  not
       apologize  for  it. :‐)  Below are the major remaining cases where this
       is known to occur.

       Certain kinds of conformant array  parameters  (including  multi‐dimen‐
       sional  conformant  arrays)  produce code that declares variable‐length
       arrays in C.  Only a few C compilers, such as the GNU C compiler,  sup‐
       port  this  language  extension.  Otherwise some hand re‐coding will be
       required.

       HP Pascal ttrryy‐rreeccoovveerr structures are translated into calls to  _T_R_Y  and
       _R_E_C_O_V_E_R  macros,  which  are  defined  to  simulate the construct using
       _s_e_t_j_m_p and _l_o_n_g_j_m_p_.  If this emulation does not work, define the symbol
       FFAAKKEE__TTRRYY  to cause these macros to become "inert."  (In cases where the
       error is detected by code physically within the body of the ttrryy  state‐
       ment,  a  C  ggoottoo  to  the rreeccoovveerr section is always generated.)  Also,
       local file variables in scopes which are destroyed by an eessccaappee are not
       closed.

       Non‐local  GOTO’s  and ttrryy‐rreeccoovveerr statements are each implemented, 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 recursion.

       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’  vari‐
       ables  are  occasionally omitted by mistake, if the access is too indi‐
       rect for _p_2_c to notice.  If this happens, you can add an explicit  ref‐
       erence  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
       _p_2_c_.

       Many  aspects of Modula‐2 are translated only superficially.  For exam‐
       ple, the type‐compatibility properties of the _W_O_R_D and  _A_R_R_A_Y  _O_F  _W_O_R_D
       types are only roughly modelled, as are the scope rules concerning mod‐
       ules.

       Parts of VAX Pascal are still untreated.  In particular,  the  _[_U_N_S_A_F_E_]
       attribute  and a few others are not fully supported, nor are the seman‐
       tics of the _O_P_E_N procedure.

       Turbo and VAX Pascal’s _d_o_u_b_l_e_, _q_u_a_d_r_u_p_l_e_, and _e_x_t_e_n_d_e_d real  types  all
       translate to the C ddoouubbllee type.  Turbo’s _c_o_m_p_u_t_a_t_i_o_n_a_l type is not sup‐
       ported 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_]_:_=_c_h_r_(_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 _o_r_d_(_s_[_0_]_)_+_n_, then the generated code will
       not work.  In VAX Pascal this corresponds to performing  arithmetic  on
       the _L_E_N_G_T_H field of a varying‐length string.

       Turbo  Pascal’s  automatic  clipping  of  strings is not supported.  In
       Turbo, if a ten character string is assigned to a  _s_t_r_i_n_g_[_8_]  variable,
       the last two characters are silently removed.  The code produced by _p_2_c
       generally will overrun the target string instead!  The SSttrriinnggTTrruunnccLLiimmiitt
       parameter  (80  by  default  if LLaanngguuaaggee=TTuurrbboo) 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 _c_o_p_y in the  Pascal  source
       to truncate the strings explicitly.

FFIILLEESS
       file._x_x_x                                                   Pascal
       source files
       file.c                                                     resulting  C
       source file
       module.h                                                   resulting  C
       header file
       p2crc                                                      local   con‐
       figuration file
       .p2crc                                                     alternate
       local configuration file
       /Users/schneidt/now/p2c/test/p2c‐1.21alpha2/home/p2crc     system‐wide
       configuration file
       /Users/schneidt/now/p2c/test/p2c‐1.21alpha2/home/system.impdeclarations
       for predefined functions
       /Users/schneidt/now/p2c/test/p2c‐1.21alpha2/home/system.m2 analogous
       declarations for Modula‐2
       /Users/schneidt/now/p2c/test/p2c‐1.21alpha2/home/*.imp     interface
       text for standard modules
       /Users/schneidt/now/p2c/test/p2c‐1.21alpha2/home/p2c/p2c.h header  file
       for translated programs
       /Users/schneidt/now/p2c/test/p2c‐1.21alpha2/home/libp2c.a  run‐time
       library

AAUUTTHHOORR
       Dave Gillespie, daveg@synaptics.com.

       Many thanks to William Bader, Steven Levi, Rick  Koshi,  Eric  Raymond,
       Magne  Haveraaen,  Dirk Grunwald, David Barto, Paul Fisher, Tom Schnei‐
       der, Dick Heijne, Guenther Sawitzki, and many others whose  suggestions
       and bug reports have helped improve _p_2_c in countless ways.



                                     local                              P2C(1)
