


P2C(1)                                                     P2C(1)


NNAAMMEE
       p2c - Pascal to C translator, version 1.20

SSYYNNOOPPSSIISS
       pp22cc [ options ] [ file [ module ] ]

DDEESSCCRRIIPPTTIIOONN
       _P_2_c is a tool for translating Pascal programs into C.  The
       input consists of a set of source files in any of the fol-
       lowing  Pascal dialects: HP Pascal, Turbo/UCSD Pascal, DEC
       VAX Pascal, Oregon Software Pascal/2,  Macintosh  Program-
       mer's Workshop Pascal, Sun/Berkeley Pascal.  Modula-2 syn-
       tax is also supported.  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 modifications, although _p_2_c  sometimes
       chooses  to generate readable code at the expense of abso-
       lute generality.  _P_2_c endeavors to insert notes and  warn-
       ing messages into the output code to point out areas which
       may require human intervention.  Output code  is  arranged
       to  be readable and efficient, and to make use of C idioms
       wherever possible.  The main goal of the translation is to
       produce C files which are pleasant and "natural" enough to
       be acceptable as the new source files for a program.  In a
       pinch, _p_2_c will also serve as an ad hoc Pascal 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.  Generated
       code does not require an ANSI-compatible compiler  (unless
       ANSI-style  code  is  requested),  but it does use various
       ANSI-standard library routines.

       All generated code includes the file _<_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 nomen-
       clature), or it may just contain a  number  of  procedures
       and  declarations.   _P_2_c  is  designed to work for correct



                              local                             1





P2C(1)                                                     P2C(1)


       input programs.  That is, it will accept partial  programs
       but  may  occasionally  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 interest-
       ing.  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  stan-
       dard  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  translated;
       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
       _/_c_d_r_o_m_/_s_o_u_r_c_e_/_d_/_p_2_c_/_p_2_c_/_h_o_m_e_/_p_2_c_r_c for a number of config-
       uration  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 interface sections omitted
              for speed, which the program or module being trans-
              lated  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.



                              local                             2





P2C(1)                                                     P2C(1)


       --pp_n    Display  progress  of  translation in the form of a
              line number/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  configu-
              ration   file   _/_c_d_r_o_m_/_s_o_u_r_c_e_/_d_/_p_2_c_/_p_2_c_/_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  sup-
              presses  the  file  named  by the P2CRC environment
              variable.

       --HH _h_o_m_e_d_i_r
              Use _h_o_m_e_d_i_r instead of _/_c_d_r_o_m_/_s_o_u_r_c_e_/_d_/_p_2_c_/_p_2_c_/_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  modules  which are imported.  The pattern
              should include a _%_s to represent the  module  name,
              and  should  evaluate  to a potential file name for
              that module's source code.  For example,  ....//%%ss..ppaass
              looks  for _m_o_d_u_l_e_n_a_m_e..ppaass in the parent of the cur-
              rent directory.

       --ii     This special option (which must be the  only  argu-
              ment on the command line if used) simply copies the
              system              configuration              file
              _/_c_d_r_o_m_/_s_o_u_r_c_e_/_d_/_p_2_c_/_p_2_c_/_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 translation.

       --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,  sur-
              rounded  by #ifdefs.  This is the same as the CCooppyy--
              SSoouurrccee parameter in the _p_2_c_r_c file.

       --aa     Produce modern ANSI C.  This is a convenient  over-
              ride for the AAnnssiiCC parameter in the _p_2_c_r_c file.



                              local                             3





P2C(1)                                                     P2C(1)


       --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 addi-
              tional ".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.

       --MM00    Disable  memory  conservation.   This  prevents _p_2_c
              from freeing various data structures  after  trans-
              lating 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.  Debugging 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, and --CC_n enables
       comment placement 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 LLaann--
       gguuaaggee 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 parameters 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 Work-
               station 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 confor-
               mant arrays and procedural parameters.

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




                              local                             4





P2C(1)                                                     P2C(1)


       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  inte-
               gers, 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 lan-
               guage features supported.  This has not  yet  been
               tested on large programs.

       OOrreeggoonn  Oregon  Software  Pascal/2.   All  features imple-
               mented.

       BBeerrkk    Berkeley Pascal with Sun extensions.

       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  edition.   Proper setting of the LLaann--
               gguuaaggee 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 identi-
               fiers 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 (implementation 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
               translate 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,



                              local                             5





P2C(1)                                                     P2C(1)


       some predefined functions may be omitted.  In these cases,
       the function call will be translated literally into C with
       a warning.  Some hand modification may be required.

CCOONNFFIIGGUURRAATTIIOONN PPAARRAAMMEETTEERRSS
       _P_2_c is highly configurable.  The defaults are suitable for
       most applications, 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, efficient, 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 configuration line adds an  entry.

       Many _p_2_c_r_c options take a numeric value of 0 or 1, roughly
       corresponding to "no" or "yes."  Sometimes a  blank  value
       or  the value "ddeeff" corresponds to an intermediate "maybe"
       state.  For  example,  the  stylistic  option  EExxttrraaPPaarreennss
       switches between copious or minimal parentheses in expres-
       sions, with the default being a nice  compromise  intended
       to  be  best  for  readers  with an average knowledge of C
       operator precedences.

       Configuration options may also be embedded in  the  source
       file in the form of Pascal comments:

            {ShortOpt=0} {AvoidName=fred}
            {FuncMacro slope(x,y)=atan2(y,x)*RadDeg}

       disables  automatic short-circuiting of aanndd and oorr expres-
       sions, 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
       embedded  parameters.  The `=' sign is required for embed-
       ded parameters, though it  is  optional  in  _p_2_c_r_c  files.
       Comments within embedded parameters 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:



                              local                             6





P2C(1)                                                     P2C(1)


            {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 declarations, without affecting the parameter's
       value elsewhere in the file.

       If an embedded parameter appears in an include file or  in
       interface  text for a module, the effect of the assignment
       normally carries over to any programs that  included  that
       file.   If  the  parameter name is preceded by a `*', then
       the assignment is automatically undone  after  the  source
       file that contains it ends:

            {IncludeFrom strings=<p2c/strings.h>}
            {*ExportSymbol=pascal_%s}
            module strings;

       will  record  the location of the _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++++            At present _p_2_c does not use much of C++  at
                      all.   The  default  action  is to generate
                      code that will compile in either  language.

       UUsseeVVEExxtteerrnn     Many  non-UNIX  linkers  prohibit variables



                              local                             7





P2C(1)                                                     P2C(1)


                      from being defined (not declared)  by  more
                      than  one  source  file.   One  module must
                      declare, e.g., "int foo;", and  all  others
                      must declare "extern int foo;".  _P_2_c accom-
                      plishes 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 vari-
                      ables  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 disable the use of
                      these  macros.   Note that the functions of
                      many  of  these  macros  can  also  be  had
                      directly  using other parameters; for exam-
                      ple,  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  portable  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  avail-
                      able.   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; low-
                      ercase cchhaarr is used when the desired  mean-
                      ing 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; lower-
                      case  ssttaattiicc is used for static local vari-
                      ables.  Thus you can redefine SSttaattiicc to  be
                      null  if you want to force private names to
                      be public for purposes of debugging.

                      The word VVooiidd expands to vvooiidd in all cases;



                              local                             8





P2C(1)                                                     P2C(1)


                      it  is  used when declaring a function with
                      no return value.   The  word  AAnnyyppttrr  is  a
                      typedef  for vvooiidd ** or cchhaarr ** as necessary;
                      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 sup-
                      ported, you instead get

                           Void foo  ();
                           Char *bar ();

                      By  default,  _p_2_c uses these macros for all
                      function declarations, 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 defin-
                      ing  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
                      omitted.   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  gen-
                      erated during output the string may need to



                              local                             9





P2C(1)                                                     P2C(1)


                      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   EExxppaannddIInn--
                      cclluuddeess=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 combining 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.

       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]" everywhere.  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 programs.

       FFoollddCCoonnssttaannttss  Pascal  non-structured  constants generally
                      translate to ##ddeeffiinnee's in C.  Set this to 1
                      to  have  constants  instantiated  directly
                      into the code.  This may be  turned  on  or
                      off  around specific constant declarations.
                      Set this to 0 to force _p_2_c  to  make  abso-
                      lutely  no assumptions about the constant's
                      value in generated code, so  that  you  can
                      change  the  constant  later  in the C code
                      without invalidating 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



                              local                            10





P2C(1)                                                     P2C(1)


                      constant is positive.

       CChhaarrCCoonnssttss     This   governs   whether   single-character
                      string  literals  in  Pascal ccoonnsstt declara-
                      tions should be interpreted  as  characters
                      or  strings.   In other words, _c_o_n_s_t _a_=_'_x_'_;
                      will translate to _#_d_e_f_i_n_e _a _'_x_' if CChhaarrCCoonn--
                      ssttss=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.

       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  creat-
                      ing  a  hidden  size  parameter  by setting
                      VVaarrSSttrriinngg=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.
                      This  also  controls  whether  to   include
                      parameter names or just their types in sit-
                      uations  where  names  are  optional.   The
                      FFuullllPPrroottoottyyppiinngg parameter allows prototypes
                      to be generated for  declarations  but  not
                      for  definitions  (older versions of Light-
                      speed C required this).  If you use a  mix-
                      ture  of  prototypes  and old-style defini-
                      tions, 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 param-
                      eter 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 pro-
                      cedures.  In HP Pascal a procedure  pointer



                              local                            11





P2C(1)                                                     P2C(1)


                      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 (SSttaattiiccLLiinnkkss=2) uses struc-
                      tures 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  opera-
                      tions.   (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  elements 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 operating 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 containing a _%_s  where
                      the relevant information should go.  In the
                      case of RReettuurrnnVVaalluueeNNaammee, the _%_s refers to a
                      function  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  con-
                      tains   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_.




                              local                            12





P2C(1)                                                     P2C(1)


       AAlltteerrnnaatteeNNaammee  _P_2_c normally translates Pascal names into C
                      names  verbatim,  but  occasionally this is
                      not possible.  A Pascal name  may  be  a  C
                      reserved  word  or  traditional C name like
                      _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 param-
                      eter  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 Pas-
                      cal  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 sym-
                      bol; 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 charac-
                      ter.  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 sym-
                      bol which  is  declared  (after  which  the
                      parameter is cleared).

       SSyynnoonnyymm        This  creates  a synonym for another Pascal
                      symbol or keyword.  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 keyword.  If
                      _n_e_w_-_n_a_m_e is the name of a predefined  func-
                      tion,  _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



                              local                            13





P2C(1)                                                     P2C(1)


                      are entirely ignored  in  the  input  file.
                      Synonyms  allow  you to skip over a keyword
                      in your  dialect  of  Pascal  that  is  not
                      understood by _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  predefined  functions  are
                      available  at  all  times;  if  you  have a
                      library routine that  behaves  like,  e.g.,
                      Turbo  Pascal's  _g_e_t_m_e_m  procedure, you can
                      make your routine a synonym 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 Pascal 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 var-
                      ious  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 specifi-
                      cally for use with Pascal  variables.   The
                      righthand  side  can  be most any C expres-
                      sion; all references to  the  variable  are
                      expanded  into  that  C  expression.  Names
                      used in the C expression are  taken  verba-
                      tim.   There is also a CCoonnssttMMaaccrroo 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
                      Pascal-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  assign-
                      ment,  _p_2_c  will use algebra to "solve" for
                      _i_.

                      In all cases where  _p_2_c  parses  C  expres-
                      sions,   all  C  operators  are  recognized



                              local                            14





P2C(1)                                                     P2C(1)


                      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  identifier
                      (built-in or defined by your program previ-
                      ously to  when  the  macro  definition  was
                      parsed),   or   an  arbitrary  Pascal  type
                      expression in  parentheses.   The  lefthand
                      argument  is  then  considered  to have the
                      specified type.  This may be  necessary  if
                      your  macro is used in situations where the
                      exact type of the expression must be  known
                      (say, as the argument to a _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
                      righthand  side must be a C expression gen-
                      erally  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 func-
                      tion or procedure  name  plus  a  parameter
                      list.   The number of parameters must match
                      the number in the function's uses and  dec-
                      laration.    Calls   to  the  function  are
                      replaced by the C expression on the  right-
                      hand side.  For example,

                           FuncMacro    PtInRect(p,r)   =   PtIn-
                      Rect(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 pro-
                      gram or module being translated, the  FFuunncc--
                      MMaaccrroo will not affect the definition but it
                      will affect all calls to the function else-
                      where  in  the module.  FFuunnccMMaaccrrooss can also
                      be applied to predefined  or  never-defined



                              local                            15





P2C(1)                                                     P2C(1)


                      functions.

       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 gen-
                      erated 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  sec-
                      tion  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 directory, then for
                      _/_c_d_r_o_m_/_s_o_u_r_c_e_/_d_/_p_2_c_/_p_2_c_/_h_o_m_e_/_%_s_._i_m_p_.
                      (where  /cdrom/source/d/p2c/p2c/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  func-
                      tions,  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  concept.   _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 configuration  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 func-
                      tions as above, but  with  the  ability  to
                      work  in-place;  that  is, the same pointer
                      may be passed as both the return value area
                      and a regular parameter.

       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



                              local                            16





P2C(1)                                                     P2C(1)


                      produce   the  same  result,  and  have  no
                      effects other than returning a value.   _P_2_c
                      can  make  use of this knowledge when opti-
                      mizing code for efficiency or  readability.
                      Functions  on this list are also assumed to
                      be relatively fast, so that it  is  accept-
                      able 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 suppressed
                      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 UUnnBBuuffffeerreedd--
                      FFiillee  allows you to force certain files _n_o_t
                      to have buffers.

       SSttrruuccttFFiilleess    If _p_2_c  still  can't  translate  your  file
                      operations  correctly,  you can set SSttrruucctt--
                      FFiilleess=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 correct
                      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



                              local                            17





P2C(1)                                                     P2C(1)


                      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 disabled.

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 IInnttSSiizzee appropriately.  In par-
       ticular 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  unneces-
       sary   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 CCaassttAArrggss param-
       eter similarly controls other  types  of  casts,  such  as
       between  ints  and doubles.)  The IInntteeggeerr1166 parameter con-
       trols 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"  interpreted  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 matters.  These comments are controlled by
       the SSiiggnneeddCCoommmmeenntt and  UUnnssiiggnneeddCCoommmmeenntt  parameters.   (The
       type  {{UUNNSSIIGGNNEEDD}} iinntteeggeerr is also recognized.)  The SSiiggnneedd--
       CChhaarr parameter tells whether C characters  are  signed  or
       unsigned (default is "unknown").  The HHaassSSiiggnneeddCChhaarr param-
       eter tells whether the phrase "signed char"  is  legal  in
       the  output.  If it is not, _p_2_c may have to translate Pas-
       cal 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  integers;  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.)



                              local                            18





P2C(1)                                                     P2C(1)


       EEmmbbeeddddeedd  ccooddee..   It is possible to write a Pascal comment
       containing C code to be embedded into the output.  See the
       descriptions of EEmmbbeeddCCoommmmeenntt and its relatives in the sys-
       tem _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.

       CCoommmmeennttss aanndd bbllaannkk lliinneess..  _P_2_c collects the comments in  a
       procedure  into  a  list.  All comments and statements are
       stamped with serial numbers which  are  used  to  reattach
       comments  to  statements  even  after code has been added,
       removed, or rearranged during translation.  "Orphan"  com-
       ments  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 indenta-
       tion 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 state-
       ments 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  pro-
       gressively  greater  penalties  for  breaking at operators
       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 pos-
       sible sets of break points.  To avoid  excessive  computa-
       tion, the total penalty contributed at each decision point
       must sum to  a  nonnegative  value;  negative  values  are
       clipped  up  to zero.  This allows _p_2_c to prune away obvi-
       ously   undesirable   alternatives   in   advance.     The



                              local                            19





P2C(1)                                                     P2C(1)


       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  vari-
       ables.   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  "PASCAL_MAIN")  to be blank.  This will work if
       argc and argv are never accessed outside of your main pro-
       gram.

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, ide-
       ally the "extreme" cases would include  only  those  which
       never  arise in real life.  Thus if _p_2_c actually 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-dimensional  conformant  arrays)  produce  code that
       declares variable-length arrays in C.  Only a few  C  com-
       pilers,  such as the GNU C compiler, support this language
       extension.   Otherwise  some  hand   re-coding   will   be
       required.

       HP Pascal 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
       statement,  a C ggoottoo to the rreeccoovveerr section is always gen-
       erated.)  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 automat-
       ically closed by DISPOSE.

       LINK variables allowing  sub-procedures  access  to  their
       parents' variables are occasionally omitted by mistake, if



                              local                            20





P2C(1)                                                     P2C(1)


       the access is too indirect for _p_2_c  to  notice.   If  this
       happens,  you  can  add  an explicit reference to a parent
       variable in the sub-procedure.  A statement  of  the  form
       "a:=a"  will  count  as  a reference but then be optimized
       away by _p_2_c_.

       Many aspects of  Modula-2  are  translated  only  superfi-
       cially.  For example, 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  mod-
       elled, as are the scope rules concerning modules.

       Parts  of  VAX Pascal are still untreated.  In particular,
       the _[_U_N_S_A_F_E_] attribute and a few others are not fully sup-
       ported, nor are the semantics 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 supported at all.

       Because  Pascal strings (with length bytes) are translated
       into C strings (with  null  terminators),  certain  Pascal
       string  tricks  will not work in the translated code.  For
       example  the  assignment  _s_[_0_]_:_=_c_h_r_(_x_)  is  translated  to
       _s_[_x_]_=_0  on  the assumption that the string is being short-
       ened.  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  corre-
       sponds  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  sup-
       ported.   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";  assign-
       ments  of  potentially-long  strings to short string vari-
       ables 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 configuration
       file
       .p2crc                                 alternate     local
       configuration file
       /cdrom/source/d/p2c/p2c/home/p2crc     system-wide config-
       uration file



                              local                            21





P2C(1)                                                     P2C(1)


       /cdrom/source/d/p2c/p2c/home/system.impdeclarations    for
       predefined functions
       /cdrom/source/d/p2c/p2c/home/system.m2 analogous  declara-
       tions for Modula-2
       /cdrom/source/d/p2c/p2c/home/*.imp     interface text  for
       standard modules
       /cdrom/source/d/p2c/p2c/home/p2c/p2c.h header   file   for
       translated programs
       /cdrom/source/d/p2c/p2c/home/libp2c.a  run-time library

AAUUTTHHOORR
       Dave Gillespie, daveg@csvax.cs.caltech.edu.

       Many thanks to William Bader,  Steven  Levi,  Rick  Koshi,
       Eric Raymond, Magne Haveraaen, Dirk Grunwald, David Barto,
       Paul Fisher, Tom Schneider, and others  whose  suggestions
       and bug reports have helped improve _p_2_c in countless ways.








































                              local                            22


