This is Info file gpc.info, produced by Makeinfo version 1.67 from the
input file gpc.texi.

   This file documents the use and the internals of the GNU Pascal
compiler.

   Copyright (C) 1988, 1996 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "GNU General Public License," "Funding for
Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "GNU General Public
License," "Funding for Free Software," and "Protect Your Freedom--Fight
`Look And Feel'", and this permission notice, may be included in
translations approved by the Free Software Foundation instead of in the
original English.


File: gpc.info,  Node: Top,  Next: Welcome,  Up: (DIR)

GNU Pascal
**********

   This manual documents how to run, install and maintain the GNU Pascal
compiler (GPC), as well as its new features and incompatibilities, and
how to report bugs.  It corresponds to GPC alpha version 980705 (GCC
version 2.8.1).

* Menu:

* Welcome::           Welcome to GNU Pascal!

* Copying::           GNU General Public License says
                      how you can copy and share GPC.
* Funding::           How to help assure funding for free software.
* Look and Feel::     Protect your freedom--fight "look and feel".
* Manifesto::         What's GNU?  GNU's Not Unix!

* Contributors::      People who have contributed to GPC.

Using GNU Pascal:

* Installation::      How to configure, compile and install GNU Pascal.
* Invoking GPC::      Command options supported by `gpc'.

(The following chapters are under development.)
* Programming::       The programmer's guide to GPC.
* Reference::         The alphabetical GPC language reference.
* GPC source::        How to get more information from the source
                      of the GNU Pascal compiler itself

(The following chapters are obsolete but might be useful for you, though.)
* Keywords::          Pascal Keywords and operators supported by GNU Pascal.
* Built-in::          Other built-in Identifiers.
* Extensions::        Extensions to Standard Pascal supported by GPC.
* Extended Pascal::   About Pascal and Extended Pascal languages.
* Borland Pascal::    A QuickStart guide from Borland Pascal to GNU Pascal.

* GPC bugs::          Known bugs and inconveniences; how to report bugs.
* Support::           How to get support with GNU Pascal.
* How to Contribute:: How you can contribute to the GNU Pascal project.

GNU Pascal Internals:

(The following chapters are obsolete but might be useful for you, though.)
* GPC notes::         Random notes about GPC.
* PVS::               Pascal Validation Suite test results.
* Set types::         Remarks about new set type implementation.

* GPC index::         Index of concepts and symbol names (incomplete).


File: gpc.info,  Node: Welcome,  Next: Copying,  Prev: Top,  Up: Top

Welcome to GNU Pascal, ...
**************************

   ... the free 32-bit Pascal compiler from the GNU family!

   The purpose of the GNU Pascal project is to produce a Pascal compiler
(called GNU Pascal or GPC) which

   * combines the clarity of Pascal with powerful tools suitable for
     real-life programming,

   * supports both the Pascal standard and the Extended Pascal standard
     as defined by ISO, ANSI and IEEE (ISO 7185:1990, ISO/IEC
     10206:1991, ANSI/IEEE 770X3.160-1989),

   * supports other Pascal standards (UCSD Pascal, Borland Pascal,
     Pascal-SC) in so far as this serves the goal of clarity and
     usability,

   * may be distributed under normal GNU license conditions, and

   * can generate code for and run on any computer for which the GNU C
     compiler can generate code and run on.

   Pascal was originally designed for teaching.  GNU Pascal provides a
smooth way to proceed to challenging programming tasks without learning
a completely different language.

   The GNU Pascal compiler is part of the GNU Compiler family combining
a language independent part of the GNU Compiler (GCC) with a Pascal
specific front end.  Other compilers of the family currently include
compilers for the Ada, C, C++, Objective C, and FORTRAN languages.

   This documentation contains

   * the GNU General Public License which informs you about your rights
     and responsibilites when using, modifying and distributing GNU
     Pascal, see *Note Copying::,

   * other texts about Free Software and the GNU Project intended to
     answer questions like "what is GNU?" you might have in mind now,
     see *Note Funding::, *Note Look and Feel::, and *Note Manifesto::,

   * a list of contributors where you can read who is responsible for
     all the bugs and trouble you are going to have with GNU Pascal, see
     *Note Contributors::,

   * installation instructions, see *Note Installation::,

   * and the current version of a "GNU Pascal manual" intended to
     describe how to use the compiler.  (Sorry about this--it's rather
     incomplete and outdated.)

   If you are familiar with Standard Pascal (ISO 7185) programming, you
can probably just go ahead and try to compile your programs.  (If
something does not work, see *Note GPC bugs::.)  The ISO Extended
Pascal Standard (ISO 10206) is only partially implemented into GNU
Pascal, see *Note Extensions::.

   If you are a Borland Pascal programmer, you should probably start
reading the QuickStart guide from Borland to GNU Pascal, see *Note
Borland Pascal::.  If you are curious about the Extended Pascal
Standard which is a standardized high-level Pascal, read the
comparision between ISO Extended Pascal and Borland Pascal, *Note
Extended Pascal::.

   In case you run into something which you consider a bug in GNU
Pascal, read the included bug list, *Note GPC bugs::.  In that chapter
you can also find information how to report the bug and how to get
quick help.

   And, please, think about how you can contribute to the GNU Pascal
project, too.  Remember that we, the authors of GNU Pascal and of the
documentation you are reading right now, do not get money for this job.
Please support our work by contributing yours in form of example
programs, bug reports, documentation, or even actual improvements of
the compiler.  A "wish list" is included; see *Note How to Contribute::.


File: gpc.info,  Node: Copying,  Next: Funding,  Prev: Welcome,  Up: Top

GNU GENERAL PUBLIC LICENSE
**************************

                         Version 2, June 1991

     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
     59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
     
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

Preamble
========

   The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

   When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it in
new free programs; and that you know you can do these things.

   To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

   For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

   We protect your rights with two steps: (1) copyright the software,
and (2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

   Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

   Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

   The precise terms and conditions for copying, distribution and
modification follow.

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. This License applies to any program or other work which contains a
     notice placed by the copyright holder saying it may be distributed
     under the terms of this General Public License.  The "Program",
     below, refers to any such program or work, and a "work based on
     the Program" means either the Program or any derivative work under
     copyright law: that is to say, a work containing the Program or a
     portion of it, either verbatim or with modifications and/or
     translated into another language.  (Hereinafter, translation is
     included without limitation in the term "modification".)  Each
     licensee is addressed as "you".

     Activities other than copying, distribution and modification are
     not covered by this License; they are outside its scope.  The act
     of running the Program is not restricted, and the output from the
     Program is covered only if its contents constitute a work based on
     the Program (independent of having been made by running the
     Program).  Whether that is true depends on what the Program does.

  1. You may copy and distribute verbatim copies of the Program's
     source code as you receive it, in any medium, provided that you
     conspicuously and appropriately publish on each copy an appropriate
     copyright notice and disclaimer of warranty; keep intact all the
     notices that refer to this License and to the absence of any
     warranty; and give any other recipients of the Program a copy of
     this License along with the Program.

     You may charge a fee for the physical act of transferring a copy,
     and you may at your option offer warranty protection in exchange
     for a fee.

  2. You may modify your copy or copies of the Program or any portion
     of it, thus forming a work based on the Program, and copy and
     distribute such modifications or work under the terms of Section 1
     above, provided that you also meet all of these conditions:

       a. You must cause the modified files to carry prominent notices
          stating that you changed the files and the date of any change.

       b. You must cause any work that you distribute or publish, that
          in whole or in part contains or is derived from the Program
          or any part thereof, to be licensed as a whole at no charge
          to all third parties under the terms of this License.

       c. If the modified program normally reads commands interactively
          when run, you must cause it, when started running for such
          interactive use in the most ordinary way, to print or display
          an announcement including an appropriate copyright notice and
          a notice that there is no warranty (or else, saying that you
          provide a warranty) and that users may redistribute the
          program under these conditions, and telling the user how to
          view a copy of this License.  (Exception: if the Program
          itself is interactive but does not normally print such an
          announcement, your work based on the Program is not required
          to print an announcement.)

     These requirements apply to the modified work as a whole.  If
     identifiable sections of that work are not derived from the
     Program, and can be reasonably considered independent and separate
     works in themselves, then this License, and its terms, do not
     apply to those sections when you distribute them as separate
     works.  But when you distribute the same sections as part of a
     whole which is a work based on the Program, the distribution of
     the whole must be on the terms of this License, whose permissions
     for other licensees extend to the entire whole, and thus to each
     and every part regardless of who wrote it.

     Thus, it is not the intent of this section to claim rights or
     contest your rights to work written entirely by you; rather, the
     intent is to exercise the right to control the distribution of
     derivative or collective works based on the Program.

     In addition, mere aggregation of another work not based on the
     Program with the Program (or with a work based on the Program) on
     a volume of a storage or distribution medium does not bring the
     other work under the scope of this License.

  3. You may copy and distribute the Program (or a work based on it,
     under Section 2) in object code or executable form under the terms
     of Sections 1 and 2 above provided that you also do one of the
     following:

       a. Accompany it with the complete corresponding machine-readable
          source code, which must be distributed under the terms of
          Sections 1 and 2 above on a medium customarily used for
          software interchange; or,

       b. Accompany it with a written offer, valid for at least three
          years, to give any third party, for a charge no more than your
          cost of physically performing source distribution, a complete
          machine-readable copy of the corresponding source code, to be
          distributed under the terms of Sections 1 and 2 above on a
          medium customarily used for software interchange; or,

       c. Accompany it with the information you received as to the offer
          to distribute corresponding source code.  (This alternative is
          allowed only for noncommercial distribution and only if you
          received the program in object code or executable form with
          such an offer, in accord with Subsection b above.)

     The source code for a work means the preferred form of the work for
     making modifications to it.  For an executable work, complete
     source code means all the source code for all modules it contains,
     plus any associated interface definition files, plus the scripts
     used to control compilation and installation of the executable.
     However, as a special exception, the source code distributed need
     not include anything that is normally distributed (in either
     source or binary form) with the major components (compiler,
     kernel, and so on) of the operating system on which the executable
     runs, unless that component itself accompanies the executable.

     If distribution of executable or object code is made by offering
     access to copy from a designated place, then offering equivalent
     access to copy the source code from the same place counts as
     distribution of the source code, even though third parties are not
     compelled to copy the source along with the object code.

  4. You may not copy, modify, sublicense, or distribute the Program
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense or distribute the Program is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

  5. You are not required to accept this License, since you have not
     signed it.  However, nothing else grants you permission to modify
     or distribute the Program or its derivative works.  These actions
     are prohibited by law if you do not accept this License.
     Therefore, by modifying or distributing the Program (or any work
     based on the Program), you indicate your acceptance of this
     License to do so, and all its terms and conditions for copying,
     distributing or modifying the Program or works based on it.

  6. Each time you redistribute the Program (or any work based on the
     Program), the recipient automatically receives a license from the
     original licensor to copy, distribute or modify the Program
     subject to these terms and conditions.  You may not impose any
     further restrictions on the recipients' exercise of the rights
     granted herein.  You are not responsible for enforcing compliance
     by third parties to this License.

  7. If, as a consequence of a court judgment or allegation of patent
     infringement or for any other reason (not limited to patent
     issues), conditions are imposed on you (whether by court order,
     agreement or otherwise) that contradict the conditions of this
     License, they do not excuse you from the conditions of this
     License.  If you cannot distribute so as to satisfy simultaneously
     your obligations under this License and any other pertinent
     obligations, then as a consequence you may not distribute the
     Program at all.  For example, if a patent license would not permit
     royalty-free redistribution of the Program by all those who
     receive copies directly or indirectly through you, then the only
     way you could satisfy both it and this License would be to refrain
     entirely from distribution of the Program.

     If any portion of this section is held invalid or unenforceable
     under any particular circumstance, the balance of the section is
     intended to apply and the section as a whole is intended to apply
     in other circumstances.

     It is not the purpose of this section to induce you to infringe any
     patents or other property right claims or to contest validity of
     any such claims; this section has the sole purpose of protecting
     the integrity of the free software distribution system, which is
     implemented by public license practices.  Many people have made
     generous contributions to the wide range of software distributed
     through that system in reliance on consistent application of that
     system; it is up to the author/donor to decide if he or she is
     willing to distribute software through any other system and a
     licensee cannot impose that choice.

     This section is intended to make thoroughly clear what is believed
     to be a consequence of the rest of this License.

  8. If the distribution and/or use of the Program is restricted in
     certain countries either by patents or by copyrighted interfaces,
     the original copyright holder who places the Program under this
     License may add an explicit geographical distribution limitation
     excluding those countries, so that distribution is permitted only
     in or among countries not thus excluded.  In such case, this
     License incorporates the limitation as if written in the body of
     this License.

  9. The Free Software Foundation may publish revised and/or new
     versions of the General Public License from time to time.  Such
     new versions will be similar in spirit to the present version, but
     may differ in detail to address new problems or concerns.

     Each version is given a distinguishing version number.  If the
     Program specifies a version number of this License which applies
     to it and "any later version", you have the option of following
     the terms and conditions either of that version or of any later
     version published by the Free Software Foundation.  If the Program
     does not specify a version number of this License, you may choose
     any version ever published by the Free Software Foundation.

 10. If you wish to incorporate parts of the Program into other free
     programs whose distribution conditions are different, write to the
     author to ask for permission.  For software which is copyrighted
     by the Free Software Foundation, write to the Free Software
     Foundation; we sometimes make exceptions for this.  Our decision
     will be guided by the two goals of preserving the free status of
     all derivatives of our free software and of promoting the sharing
     and reuse of software generally.

                                NO WARRANTY

 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
     WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
     LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
     HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
     NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
     QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
     PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
     SERVICING, REPAIR OR CORRECTION.

 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
     MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
     INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
     OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
     OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

                      END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs
=============================================

   If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

   To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

     ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
     Copyright (C) 19YY  NAME OF AUTHOR
     
     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.
     
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
     
     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

   Also add information on how to contact you by electronic and paper
mail.

   If the program is interactive, make it output a short notice like
this when it starts in an interactive mode:

     Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
     type `show w'.
     This is free software, and you are welcome to redistribute it
     under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items--whatever suits your
program.

   You should also get your employer (if you work as a programmer) or
your school, if any, to sign a "copyright disclaimer" for the program,
if necessary.  Here is a sample; alter the names:

     Yoyodyne, Inc., hereby disclaims all copyright interest in the program
     `Gnomovision' (which makes passes at compilers) written by James Hacker.
     
     SIGNATURE OF TY COON, 1 April 1989
     Ty Coon, President of Vice

   This General Public License does not permit incorporating your
program into proprietary programs.  If your program is a subroutine
library, you may consider it more useful to permit linking proprietary
applications with the library.  If this is what you want to do, use the
GNU Library General Public License instead of this License.


File: gpc.info,  Node: Funding,  Next: Look and Feel,  Prev: Copying,  Up: Top

Funding Free Software
*********************

   If you want to have more free software a few years from now, it makes
sense for you to help encourage people to contribute funds for its
development.  The most effective approach known is to encourage
commercial redistributors to donate.

   Users of free software systems can boost the pace of development by
encouraging for-a-fee distributors to donate part of their selling price
to free software developers--the Free Software Foundation, and others.

   The way to convince distributors to do this is to demand it and
expect it from them.  So when you compare distributors, judge them
partly by how much they give to free software development.  Show
distributors they must compete to be the one who gives the most.

   To make this approach work, you must insist on numbers that you can
compare, such as, "We will donate ten dollars to the Frobnitz project
for each disk sold."  Don't be satisfied with a vague promise, such as
"A portion of the profits are donated," since it doesn't give a basis
for comparison.

   Even a precise fraction "of the profits from this disk" is not very
meaningful, since creative accounting and unrelated business decisions
can greatly alter what fraction of the sales price counts as profit.
If the price you pay is $50, ten percent of the profit is probably less
than a dollar; it might be a few cents, or nothing at all.

   Some redistributors do development work themselves.  This is useful
too; but to keep everyone honest, you need to inquire how much they do,
and what kind.  Some kinds of development make much more long-term
difference than others.  For example, maintaining a separate version of
a program contributes very little; maintaining the standard version of a
program for the whole community contributes much.  Easy new ports
contribute little, since someone else would surely do them; difficult
ports such as adding a new CPU to the GNU C compiler contribute more;
major new features or packages contribute the most.

   By establishing the idea that supporting further development is "the
proper thing to do" when distributing free software for a fee, we can
assure a steady flow of resources into making more free software.

     Copyright (C) 1994 Free Software Foundation, Inc.
     Verbatim copying and redistribution of this section is permitted
     without royalty; alteration is not permitted.


File: gpc.info,  Node: Look and Feel,  Next: Manifesto,  Prev: Funding,  Up: Top

Protect Your Freedom--Fight "Look And Feel"
*******************************************

     This section is a political message from the League for Programming
     Freedom to the users of GNU CC.  We have included it here because
     the issue of interface copyright is important to the GNU project.

   Apple, Lotus, and now CDC have tried to create a new form of legal
monopoly: a copyright on a user interface.

   An interface is a kind of language--a set of conventions for
communication between two entities, human or machine.  Until a few years
ago, the law seemed clear: interfaces were outside the domain of
copyright, so programmers could program freely and implement whatever
interface the users demanded.  Imitating de-facto standard interfaces,
sometimes with improvements, was standard practice in the computer
field.  These improvements, if accepted by the users, caught on and
became the norm; in this way, much progress took place.

   Computer users, and most software developers, were happy with this
state of affairs.  However, large companies such as Apple and Lotus
would prefer a different system--one in which they can own interfaces
and thereby rid themselves of all serious competitors.  They hope that
interface copyright will give them, in effect, monopolies on major
classes of software.

   Other large companies such as IBM and Digital also favor interface
monopolies, for the same reason: if languages become property, they
expect to own many de-facto standard languages.  But Apple and Lotus are
the ones who have actually sued.  Apple's lawsuit was defeated, for
reasons only partly related to the general issue of interface copyright.

   Lotus won lawsuits against two small companies, which were thus put
out of business.  Then they sued Borland; they won in the trial court
(no surprise, since it was the same court that had ruled for Lotus twice
before), but the decision was reversed by the court of appeals, with
help from the League for Programming Freedom in the form of a
friend-of-the-court brief.  We are now waiting to see if the Supreme
Court will hear the case.  If it does, the League for Programming
Freedom will again submit a brief.

   The battle is not over.  Just this summer a company that produced a
simulator for a CDC computer was shut down by a copyright lawsuit by
CDC, which charged that the simulator infringed the copyright on the
manuals for the computer.

   If the monopolists get their way, they will hobble the software
field:

   * Gratuitous incompatibilities will burden users.  Imagine if each
     car manufacturer had to design a different way to start, stop, and
     steer a car.

   * Users will be "locked in" to whichever interface they learn; then
     they will be prisoners of one supplier, who will charge a
     monopolistic price.

   * Large companies have an unfair advantage wherever lawsuits become
     commonplace.  Since they can afford to sue, they can intimidate
     smaller developers with threats even when they don't really have a
     case.

   * Interface improvements will come slower, since incremental
     evolution through creative partial imitation will no longer occur.

   If interface monopolies are accepted, other large companies are
waiting to grab theirs:

   * Adobe is expected to claim a monopoly on the interfaces of various
     popular application programs, if Lotus ultimately wins the case
     against Borland.

   * Open Computing magazine reported a Microsoft vice president as
     threatening to sue people who imitate the interface of Windows.

   Users invest a great deal of time and money in learning to use
computer interfaces.  Far more, in fact, than software developers
invest in developing *and even implementing* the interfaces.  Whoever
can own an interface, has made its users into captives, and
misappropriated their investment.

   To protect our freedom from monopolies like these, a group of
programmers and users have formed a grass-roots political organization,
the League for Programming Freedom.

   The purpose of the League is to oppose monopolistic practices such as
interface copyright and software patents.  The League calls for a return
to the legal policies of the recent past, in which programmers could
program freely.  The League is not concerned with free software as an
issue, and is not affiliated with the Free Software Foundation.

   The League's activities include publicizing the issues, as is being
done here, and filing friend-of-the-court briefs on behalf of
defendants sued by monopolists.

   The League's membership rolls include Donald Knuth, the foremost
authority on algorithms, John McCarthy, inventor of Lisp, Marvin Minsky,
founder of the MIT Artificial Intelligence lab, Guy L.  Steele, Jr.,
author of well-known books on Lisp and C, as well as Richard Stallman,
the developer of GNU CC.  Please join and add your name to the list.
Membership dues in the League are $42 per year for programmers, managers
and professionals; $10.50 for students; $21 for others.

   Activist members are especially important, but members who have no
time to give are also important.  Surveys at major ACM conferences have
indicated a vast majority of attendees agree with the League on both
issues (interface copyrights and software patents).  If just ten percent
of the programmers who agree with the League join the League, we will
probably triumph.

   To join, or for more information, phone (617) 243-4091 or write to:

     League for Programming Freedom
     1 Kendall Square #143
     P.O. Box 9171
     Cambridge, MA 02139

   You can also send electronic mail to `lpf@uunet.uu.net'.

   In addition to joining the League, here are some suggestions from the
League for other things you can do to protect your freedom to write
programs:

   * Tell your friends and colleagues about this issue and how it
     threatens to ruin the computer industry.

   * Mention that you are a League member in your `.signature', and
     mention the League's email address for inquiries.

   * Ask the companies you consider working for or working with to make
     statements against software monopolies, and give preference to
     those that do.

   * When employers ask you to sign contracts giving them copyright on
     your work, insist on a clause saying they will not claim the
     copyright covers imitating the interface.

   * When employers ask you to sign contracts giving them patent rights,
     insist on clauses saying they can use these rights only
     defensively.  Don't rely on "company policy," since that can
     change at any time; don't rely on an individual executive's
     private word, since that person may be replaced.  Get a commitment
     just as binding as the commitment they get from you.

   * Write to Congress to explain the importance of these issues.

          House Subcommittee on Intellectual Property
          2137 Rayburn Bldg
          Washington, DC 20515
          
          Senate Subcommittee on Patents, Trademarks and Copyrights
          United States Senate
          Washington, DC 20510

     (These committees have received lots of mail already; let's give
     them even more.)

   Democracy means nothing if you don't use it.  Stand up and be
counted!


File: gpc.info,  Node: Manifesto,  Next: Contributors,  Prev: Look and Feel,  Up: Top

The GNU Manifesto
*****************

     The GNU Manifesto which appears below was written by Richard
     Stallman at the beginning of the GNU project, to ask for
     participation and support.  For the first few years, it was
     updated in minor ways to account for developments, but now it
     seems best to leave it unchanged as most people have seen it.

     Since that time, we have learned about certain common
     misunderstandings that different wording could help avoid.
     Footnotes added in 1993 help clarify these points.

     For up-to-date information about the available GNU software,
     please see the latest issue of the GNU's Bulletin.  The list is
     much too long to include here.

What's GNU?  Gnu's Not Unix!
============================

   GNU, which stands for Gnu's Not Unix, is the name for the complete
Unix-compatible software system which I am writing so that I can give it
away free to everyone who can use it.(1) Several other volunteers are
helping me.  Contributions of time, money, programs and equipment are
greatly needed.

   So far we have an Emacs text editor with Lisp for writing editor
commands, a source level debugger, a yacc-compatible parser generator,
a linker, and around 35 utilities.  A shell (command interpreter) is
nearly completed.  A new portable optimizing C compiler has compiled
itself and may be released this year.  An initial kernel exists but
many more features are needed to emulate Unix.  When the kernel and
compiler are finished, it will be possible to distribute a GNU system
suitable for program development.  We will use TeX as our text
formatter, but an nroff is being worked on.  We will use the free,
portable X window system as well.  After this we will add a portable
Common Lisp, an Empire game, a spreadsheet, and hundreds of other
things, plus on-line documentation.  We hope to supply, eventually,
everything useful that normally comes with a Unix system, and more.

   GNU will be able to run Unix programs, but will not be identical to
Unix.  We will make all improvements that are convenient, based on our
experience with other operating systems.  In particular, we plan to
have longer file names, file version numbers, a crashproof file system,
file name completion perhaps, terminal-independent display support, and
perhaps eventually a Lisp-based window system through which several
Lisp programs and ordinary Unix programs can share a screen.  Both C
and Lisp will be available as system programming languages.  We will
try to support UUCP, MIT Chaosnet, and Internet protocols for
communication.

   GNU is aimed initially at machines in the 68000/16000 class with
virtual memory, because they are the easiest machines to make it run
on.  The extra effort to make it run on smaller machines will be left
to someone who wants to use it on them.

   To avoid horrible confusion, please pronounce the `G' in the word
`GNU' when it is the name of this project.

Why I Must Write GNU
====================

   I consider that the golden rule requires that if I like a program I
must share it with other people who like it.  Software sellers want to
divide the users and conquer them, making each user agree not to share
with others.  I refuse to break solidarity with other users in this
way.  I cannot in good conscience sign a nondisclosure agreement or a
software license agreement.  For years I worked within the Artificial
Intelligence Lab to resist such tendencies and other inhospitalities,
but eventually they had gone too far: I could not remain in an
institution where such things are done for me against my will.

   So that I can continue to use computers without dishonor, I have
decided to put together a sufficient body of free software so that I
will be able to get along without any software that is not free.  I
have resigned from the AI lab to deny MIT any legal excuse to prevent
me from giving GNU away.

Why GNU Will Be Compatible with Unix
====================================

   Unix is not my ideal system, but it is not too bad.  The essential
features of Unix seem to be good ones, and I think I can fill in what
Unix lacks without spoiling them.  And a system compatible with Unix
would be convenient for many other people to adopt.

How GNU Will Be Available
=========================

   GNU is not in the public domain.  Everyone will be permitted to
modify and redistribute GNU, but no distributor will be allowed to
restrict its further redistribution.  That is to say, proprietary
modifications will not be allowed.  I want to make sure that all
versions of GNU remain free.

Why Many Other Programmers Want to Help
=======================================

   I have found many other programmers who are excited about GNU and
want to help.

   Many programmers are unhappy about the commercialization of system
software.  It may enable them to make more money, but it requires them
to feel in conflict with other programmers in general rather than feel
as comrades.  The fundamental act of friendship among programmers is the
sharing of programs; marketing arrangements now typically used
essentially forbid programmers to treat others as friends.  The
purchaser of software must choose between friendship and obeying the
law.  Naturally, many decide that friendship is more important.  But
those who believe in law often do not feel at ease with either choice.
They become cynical and think that programming is just a way of making
money.

   By working on and using GNU rather than proprietary programs, we can
be hospitable to everyone and obey the law.  In addition, GNU serves as
an example to inspire and a banner to rally others to join us in
sharing.  This can give us a feeling of harmony which is impossible if
we use software that is not free.  For about half the programmers I
talk to, this is an important happiness that money cannot replace.

How You Can Contribute
======================

   I am asking computer manufacturers for donations of machines and
money.  I'm asking individuals for donations of programs and work.

   One consequence you can expect if you donate machines is that GNU
will run on them at an early date.  The machines should be complete,
ready to use systems, approved for use in a residential area, and not
in need of sophisticated cooling or power.

   I have found very many programmers eager to contribute part-time
work for GNU.  For most projects, such part-time distributed work would
be very hard to coordinate; the independently-written parts would not
work together.  But for the particular task of replacing Unix, this
problem is absent.  A complete Unix system contains hundreds of utility
programs, each of which is documented separately.  Most interface
specifications are fixed by Unix compatibility.  If each contributor
can write a compatible replacement for a single Unix utility, and make
it work properly in place of the original on a Unix system, then these
utilities will work right when put together.  Even allowing for Murphy
to create a few unexpected problems, assembling these components will
be a feasible task.  (The kernel will require closer communication and
will be worked on by a small, tight group.)

   If I get donations of money, I may be able to hire a few people full
or part time.  The salary won't be high by programmers' standards, but
I'm looking for people for whom building community spirit is as
important as making money.  I view this as a way of enabling dedicated
people to devote their full energies to working on GNU by sparing them
the need to make a living in another way.

Why All Computer Users Will Benefit
===================================

   Once GNU is written, everyone will be able to obtain good system
software free, just like air.(2)

   This means much more than just saving everyone the price of a Unix
license.  It means that much wasteful duplication of system programming
effort will be avoided.  This effort can go instead into advancing the
state of the art.

   Complete system sources will be available to everyone.  As a result,
a user who needs changes in the system will always be free to make them
himself, or hire any available programmer or company to make them for
him.  Users will no longer be at the mercy of one programmer or company
which owns the sources and is in sole position to make changes.

   Schools will be able to provide a much more educational environment
by encouraging all students to study and improve the system code.
Harvard's computer lab used to have the policy that no program could be
installed on the system if its sources were not on public display, and
upheld it by actually refusing to install certain programs.  I was very
much inspired by this.

   Finally, the overhead of considering who owns the system software
and what one is or is not entitled to do with it will be lifted.

   Arrangements to make people pay for using a program, including
licensing of copies, always incur a tremendous cost to society through
the cumbersome mechanisms necessary to figure out how much (that is,
which programs) a person must pay for.  And only a police state can
force everyone to obey them.  Consider a space station where air must
be manufactured at great cost: charging each breather per liter of air
may be fair, but wearing the metered gas mask all day and all night is
intolerable even if everyone can afford to pay the air bill.  And the
TV cameras everywhere to see if you ever take the mask off are
outrageous.  It's better to support the air plant with a head tax and
chuck the masks.

   Copying all or parts of a program is as natural to a programmer as
breathing, and as productive.  It ought to be as free.

Some Easily Rebutted Objections to GNU's Goals
==============================================

     "Nobody will use it if it is free, because that means they can't
     rely on any support."

     "You have to charge for the program to pay for providing the
     support."

   If people would rather pay for GNU plus service than get GNU free
without service, a company to provide just service to people who have
obtained GNU free ought to be profitable.(3)

   We must distinguish between support in the form of real programming
work and mere handholding.  The former is something one cannot rely on
from a software vendor.  If your problem is not shared by enough
people, the vendor will tell you to get lost.

   If your business needs to be able to rely on support, the only way
is to have all the necessary sources and tools.  Then you can hire any
available person to fix your problem; you are not at the mercy of any
individual.  With Unix, the price of sources puts this out of
consideration for most businesses.  With GNU this will be easy.  It is
still possible for there to be no available competent person, but this
problem cannot be blamed on distribution arrangements.  GNU does not
eliminate all the world's problems, only some of them.

   Meanwhile, the users who know nothing about computers need
handholding: doing things for them which they could easily do
themselves but don't know how.

   Such services could be provided by companies that sell just
hand-holding and repair service.  If it is true that users would rather
spend money and get a product with service, they will also be willing
to buy the service having got the product free.  The service companies
will compete in quality and price; users will not be tied to any
particular one.  Meanwhile, those of us who don't need the service
should be able to use the program without paying for the service.

     "You cannot reach many people without advertising, and you must
     charge for the program to support that."

     "It's no use advertising a program people can get free."

   There are various forms of free or very cheap publicity that can be
used to inform numbers of computer users about something like GNU.  But
it may be true that one can reach more microcomputer users with
advertising.  If this is really so, a business which advertises the
service of copying and mailing GNU for a fee ought to be successful
enough to pay for its advertising and more.  This way, only the users
who benefit from the advertising pay for it.

   On the other hand, if many people get GNU from their friends, and
such companies don't succeed, this will show that advertising was not
really necessary to spread GNU.  Why is it that free market advocates
don't want to let the free market decide this?(4)

     "My company needs a proprietary operating system to get a
     competitive edge."

   GNU will remove operating system software from the realm of
competition.  You will not be able to get an edge in this area, but
neither will your competitors be able to get an edge over you.  You and
they will compete in other areas, while benefiting mutually in this
one.  If your business is selling an operating system, you will not
like GNU, but that's tough on you.  If your business is something else,
GNU can save you from being pushed into the expensive business of
selling operating systems.

   I would like to see GNU development supported by gifts from many
manufacturers and users, reducing the cost to each.(5)

     "Don't programmers deserve a reward for their creativity?"

   If anything deserves a reward, it is social contribution.
Creativity can be a social contribution, but only in so far as society
is free to use the results.  If programmers deserve to be rewarded for
creating innovative programs, by the same token they deserve to be
punished if they restrict the use of these programs.

     "Shouldn't a programmer be able to ask for a reward for his
     creativity?"

   There is nothing wrong with wanting pay for work, or seeking to
maximize one's income, as long as one does not use means that are
destructive.  But the means customary in the field of software today
are based on destruction.

   Extracting money from users of a program by restricting their use of
it is destructive because the restrictions reduce the amount and the
ways that the program can be used.  This reduces the amount of wealth
that humanity derives from the program.  When there is a deliberate
choice to restrict, the harmful consequences are deliberate destruction.

   The reason a good citizen does not use such destructive means to
become wealthier is that, if everyone did so, we would all become
poorer from the mutual destructiveness.  This is Kantian ethics; or,
the Golden Rule.  Since I do not like the consequences that result if
everyone hoards information, I am required to consider it wrong for one
to do so.  Specifically, the desire to be rewarded for one's creativity
does not justify depriving the world in general of all or part of that
creativity.

     "Won't programmers starve?"

   I could answer that nobody is forced to be a programmer.  Most of us
cannot manage to get any money for standing on the street and making
faces.  But we are not, as a result, condemned to spend our lives
standing on the street making faces, and starving.  We do something
else.

   But that is the wrong answer because it accepts the questioner's
implicit assumption: that without ownership of software, programmers
cannot possibly be paid a cent.  Supposedly it is all or nothing.

   The real reason programmers will not starve is that it will still be
possible for them to get paid for programming; just not paid as much as
now.

   Restricting copying is not the only basis for business in software.
It is the most common basis because it brings in the most money.  If it
were prohibited, or rejected by the customer, software business would
move to other bases of organization which are now used less often.
There are always numerous ways to organize any kind of business.

   Probably programming will not be as lucrative on the new basis as it
is now.  But that is not an argument against the change.  It is not
considered an injustice that sales clerks make the salaries that they
now do.  If programmers made the same, that would not be an injustice
either.  (In practice they would still make considerably more than
that.)

     "Don't people have a right to control how their creativity is
     used?"

   "Control over the use of one's ideas" really constitutes control over
other people's lives; and it is usually used to make their lives more
difficult.

   People who have studied the issue of intellectual property rights
carefully (such as lawyers) say that there is no intrinsic right to
intellectual property.  The kinds of supposed intellectual property
rights that the government recognizes were created by specific acts of
legislation for specific purposes.

   For example, the patent system was established to encourage
inventors to disclose the details of their inventions.  Its purpose was
to help society rather than to help inventors.  At the time, the life
span of 17 years for a patent was short compared with the rate of
advance of the state of the art.  Since patents are an issue only among
manufacturers, for whom the cost and effort of a license agreement are
small compared with setting up production, the patents often do not do
much harm.  They do not obstruct most individuals who use patented
products.

   The idea of copyright did not exist in ancient times, when authors
frequently copied other authors at length in works of non-fiction.  This
practice was useful, and is the only way many authors' works have
survived even in part.  The copyright system was created expressly for
the purpose of encouraging authorship.  In the domain for which it was
invented--books, which could be copied economically only on a printing
press--it did little harm, and did not obstruct most of the individuals
who read the books.

   All intellectual property rights are just licenses granted by society
because it was thought, rightly or wrongly, that society as a whole
would benefit by granting them.  But in any particular situation, we
have to ask: are we really better off granting such license?  What kind
of act are we licensing a person to do?

   The case of programs today is very different from that of books a
hundred years ago.  The fact that the easiest way to copy a program is
from one neighbor to another, the fact that a program has both source
code and object code which are distinct, and the fact that a program is
used rather than read and enjoyed, combine to create a situation in
which a person who enforces a copyright is harming society as a whole
both materially and spiritually; in which a person should not do so
regardless of whether the law enables him to.

     "Competition makes things get done better."

   The paradigm of competition is a race: by rewarding the winner, we
encourage everyone to run faster.  When capitalism really works this
way, it does a good job; but its defenders are wrong in assuming it
always works this way.  If the runners forget why the reward is offered
and become intent on winning, no matter how, they may find other
strategies--such as, attacking other runners.  If the runners get into
a fist fight, they will all finish late.

   Proprietary and secret software is the moral equivalent of runners
in a fist fight.  Sad to say, the only referee we've got does not seem
to object to fights; he just regulates them ("For every ten yards you
run, you can fire one shot").  He really ought to break them up, and
penalize runners for even trying to fight.

     "Won't everyone stop programming without a monetary incentive?"

   Actually, many people will program with absolutely no monetary
incentive.  Programming has an irresistible fascination for some
people, usually the people who are best at it.  There is no shortage of
professional musicians who keep at it even though they have no hope of
making a living that way.

   But really this question, though commonly asked, is not appropriate
to the situation.  Pay for programmers will not disappear, only become
less.  So the right question is, will anyone program with a reduced
monetary incentive?  My experience shows that they will.

   For more than ten years, many of the world's best programmers worked
at the Artificial Intelligence Lab for far less money than they could
have had anywhere else.  They got many kinds of non-monetary rewards:
fame and appreciation, for example.  And creativity is also fun, a
reward in itself.

   Then most of them left when offered a chance to do the same
interesting work for a lot of money.

   What the facts show is that people will program for reasons other
than riches; but if given a chance to make a lot of money as well, they
will come to expect and demand it.  Low-paying organizations do poorly
in competition with high-paying ones, but they do not have to do badly
if the high-paying ones are banned.

     "We need the programmers desperately.  If they demand that we stop
     helping our neighbors, we have to obey."

   You're never so desperate that you have to obey this sort of demand.
Remember: millions for defense, but not a cent for tribute!

     "Programmers need to make a living somehow."

   In the short run, this is true.  However, there are plenty of ways
that programmers could make a living without selling the right to use a
program.  This way is customary now because it brings programmers and
businessmen the most money, not because it is the only way to make a
living.  It is easy to find other ways if you want to find them.  Here
are a number of examples.

   A manufacturer introducing a new computer will pay for the porting of
operating systems onto the new hardware.

   The sale of teaching, hand-holding and maintenance services could
also employ programmers.

   People with new ideas could distribute programs as freeware, asking
for donations from satisfied users, or selling hand-holding services.
I have met people who are already working this way successfully.

   Users with related needs can form users' groups, and pay dues.  A
group would contract with programming companies to write programs that
the group's members would like to use.

   All sorts of development can be funded with a Software Tax:

     Suppose everyone who buys a computer has to pay x percent of the
     price as a software tax.  The government gives this to an agency
     like the NSF to spend on software development.

     But if the computer buyer makes a donation to software development
     himself, he can take a credit against the tax.  He can donate to
     the project of his own choosing--often, chosen because he hopes to
     use the results when it is done.  He can take a credit for any
     amount of donation up to the total tax he had to pay.

     The total tax rate could be decided by a vote of the payers of the
     tax, weighted according to the amount they will be taxed on.

     The consequences:

        * The computer-using community supports software development.

        * This community decides what level of support is needed.

        * Users who care which projects their share is spent on can
          choose this for themselves.

   In the long run, making programs free is a step toward the
post-scarcity world, where nobody will have to work very hard just to
make a living.  People will be free to devote themselves to activities
that are fun, such as programming, after spending the necessary ten
hours a week on required tasks such as legislation, family counseling,
robot repair and asteroid prospecting.  There will be no need to be
able to make a living from programming.

   We have already greatly reduced the amount of work that the whole
society must do for its actual productivity, but only a little of this
has translated itself into leisure for workers because much
nonproductive activity is required to accompany productive activity.
The main causes of this are bureaucracy and isometric struggles against
competition.  Free software will greatly reduce these drains in the
area of software production.  We must do this, in order for technical
gains in productivity to translate into less work for us.

   ---------- Footnotes ----------

   (1)  The wording here was careless.  The intention was that nobody
would have to pay for *permission* to use the GNU system.  But the
words don't make this clear, and people often interpret them as saying
that copies of GNU should always be distributed at little or no charge.
That was never the intent; later on, the manifesto mentions the
possibility of companies providing the service of distribution for a
profit.  Subsequently I have learned to distinguish carefully between
"free" in the sense of freedom and "free" in the sense of price.  Free
software is software that users have the freedom to distribute and
change.  Some users may obtain copies at no charge, while others pay to
obtain copies--and if the funds help support improving the software, so
much the better.  The important thing is that everyone who has a copy
has the freedom to cooperate with others in using it.

   (2)  This is another place I failed to distinguish carefully between
the two different meanings of "free".  The statement as it stands is
not false--you can get copies of GNU software at no charge, from your
friends or over the net.  But it does suggest the wrong idea.

   (3)  Several such companies now exist.

   (4)  The Free Software Foundation raises most of its funds from a
distribution service, although it is a charity rather than a company.
If *no one* chooses to obtain copies by ordering from the FSF, it will
be unable to do its work.  But this does not mean that proprietary
restrictions are justified to force every user to pay.  If a small
fraction of all the users order copies from the FSF, that is sufficient
to keep the FSF afloat.  So we ask users to choose to support us in
this way.  Have you done your part?

   (5)  A group of computer companies recently pooled funds to support
maintenance of the GNU C Compiler.


File: gpc.info,  Node: Contributors,  Next: Installation,  Prev: Manifesto,  Up: Top

Contributors to GNU Pascal
**************************

   GNU Pascal is the work of Jukka Virtanen who invented GNU Pascal in
March 1988, implemented the ISO-7185 and most of the ISO-10206
standard, etc.  Several people have contributed to GNU Pascal:

   * Peter Gerwinski added Borland-Pascal-related and other extensions
     to GNU Pascal in summer 1995, ported GPC to EMX, does some other
     administrative stuff, etc.

   * Jan-Jaap van der Heijden ported GPC to DJGPP and to Microsoft
     Windows 95/NT, added ELF support in spring 1996, solved a lot of
     configuration and compatibility problems, etc.

   * Alexey Volokhov improved the performance of GPC's Module (Unit)
     support in June 1997.

   A lot of profit for the GNU Pascal project resulted from independent
work (which is not part of this distribution):

   * Berend de Boeur wrote a lot of useful documentation about Extended
     Pascal in 1995.

   * Phil Nelson created Pascal's bug report system in October 1996 and
     maintains it.

   * Markus Gerwinski contributed the drawing showing Gnu with Blaise
     Pascal in October 1996.

   * Robert Hoehne wrote the RHIDE, an integrated development
     environment for GNU compilers running under DOS (DJGPP) and added
     support for GNU Pascal in autumn 1996.

   * Sven Hilscher contributed a "Graph" compatible graphics Unit for
     some platforms in December 1996.

   * Abimbola A. Olowofoyeku is the author of the `BPcompat' package
     from version 1.0 on in May 1997.

   * Dario Anzani contributed documentation about the use of assembler
     in GNU Pascal in May 1997.

   GNU Pascal is based on GNU CC by Richard Stallman.  Several people
have contributed to GNU CC:

   * The idea of using RTL and some of the optimization ideas came from
     the program PO written at the University of Arizona by Jack
     Davidson and Christopher Fraser.  See "Register Allocation and
     Exhaustive Peephole Optimization", Software Practice and
     Experience 14 (9), Sept. 1984, 857-866.

   * Paul Rubin wrote most of the preprocessor.

   * Leonard Tower wrote parts of the parser, RTL generator, and RTL
     definitions, and of the Vax machine description.

   * Ted Lemon wrote parts of the RTL reader and printer.

   * Jim Wilson implemented loop strength reduction and some other loop
     optimizations.

   * Nobuyuki Hikichi of Software Research Associates, Tokyo,
     contributed the support for the Sony NEWS machine.

   * Charles LaBrec contributed the support for the Integrated Solutions
     68020 system.

   * Michael Tiemann of Cygnus Support wrote the support for inline
     functions and instruction scheduling.  Also the descriptions of the
     National Semiconductor 32000 series cpu, the SPARC cpu and part of
     the Motorola 88000 cpu.

   * Jan Stein of the Chalmers Computer Society provided support for
     Genix, as well as part of the 32000 machine description.

   * Randy Smith finished the Sun FPA support.

   * Robert Brown implemented the support for Encore 32000 systems.

   * David Kashtan of SRI adapted GNU CC to VMS.

   * Alex Crain provided changes for the 3b1.

   * Greg Satz and Chris Hanson assisted in making GNU CC work on HP-UX
     for the 9000 series 300.

   * William Schelter did most of the work on the Intel 80386 support.

   * Christopher Smith did the port for Convex machines.

   * Paul Petersen wrote the machine description for the Alliant FX/8.

   * Dario Dariol contributed the four varieties of sample programs
     that print a copy of their source.

   * Alain Lichnewsky ported GNU CC to the Mips cpu.

   * Devon Bowen, Dale Wiles and Kevin Zachmann ported GNU CC to the
     Tahoe.

   * Jonathan Stone wrote the machine description for the Pyramid
     computer.

   * Gary Miller ported GNU CC to Charles River Data Systems machines.

   * Richard Kenner of the New York University Ultracomputer Research
     Laboratory wrote the machine descriptions for the AMD 29000, the
     DEC Alpha, the IBM RT PC, and the IBM RS/6000 as well as the
     support for instruction attributes.  He also made changes to
     better support RISC processors including changes to common
     subexpression elimination, strength reduction, function calling
     sequence handling, and condition code support, in addition to
     generalizing the code for frame pointer elimination.

   * Richard Kenner and Michael Tiemann jointly developed reorg.c, the
     delay slot scheduler.

   * Mike Meissner and Tom Wood of Data General finished the port to the
     Motorola 88000.

   * Masanobu Yuhara of Fujitsu Laboratories implemented the machine
     description for the Tron architecture (specifically, the Gmicro).

   * James van Artsdalen wrote the code that makes efficient use of the
     Intel 80387 register stack.

   * Mike Meissner at the Open Software Foundation finished the port to
     the MIPS cpu, including adding ECOFF debug support, and worked on
     the Intel port for the Intel 80386 cpu.

   * Ron Guilmette implemented the `protoize' and `unprotoize' tools,
     the support for Dwarf symbolic debugging information, and much of
     the support for System V Release 4.  He has also worked heavily on
     the Intel 386 and 860 support.

   * Torbjorn Granlund implemented multiply- and divide-by-constant
     optimization, improved long long support, and improved leaf
     function register allocation.

   * Mike Stump implemented the support for Elxsi 64 bit CPU.

   * John Wehle added the machine description for the Western Electric
     32000 processor used in several 3b series machines (no relation to
     the National Semiconductor 32000 processor).


File: gpc.info,  Node: Installation,  Next: Invoking GPC,  Prev: Contributors,  Up: Top

Installing GNU Pascal
*********************

* Menu:

* compilation notes::     Configuration dependent compilation notes.
* cross-compilers::       Building and Installing a cross-compiler.
* binary distributions::  How to install a binary distribution.

   The preferred way to distribute GNU software is distribution of the
source code.  However, it can be a non-trivial exercise to build GNU
Pascal on some non-UNIX systems, so we also provide ready-to-run
binaries for a number of platforms. See *Note binary distributions:: how
to install a binary distribution.

   GPC is based on GNU CC; you will need the GCC sources to build it. It
must be the same version as the one GPC is implemented with. Although
you need GCC to build the GNU Pascal compiler, you don't need GCC to
compile Pascal programs once GNU Pascal is installed. Because GNU Pascal
shares its backend with GNU CC, it should run on any system supported by
GNU CC. A full list of platforms supported by GNU CC can be found in
*Note the GCC installation instructions: (gcc)Installation.

   Here is the generic procedure for installing GNU Pascal on a UNIX
system.  See *Note compilation notes:: for extra information needed to
install GPC on certain platforms.

  1. Unpack the source distributions.

     From a directory of your choice (e.g. `/usr/local/src'), unpack
     the GNU CC and GNU Pascal source distributions.  This will create
     separate subdirectories for GCC and GPC.

     `cd' to the GPC directory (`/usr/local/src/gpc' in the example
     above) and move the contents (a subdirectory `p') to the GCC
     directory (for instance `usr/local/src/gcc-2.8.1').

     Next, go to the GCC source directory and apply the GCC patch
     required by GNU Pascal:

          % patch -s -p1 < p/diffs/gcc-2.8.1.diff

     Note 1: If you omit this step, `configure' (see below) will prompt
     you for doing this automatically.

     Note 2: In the example above, GCC version 2.8.1 is assumed.  If
     your version of GCC is other than 2.8.1, you have to get and apply
     the appropriate patch.  If you run the patch automatically from
     `configure', it will detect and work with some versions of EGCS.

     Note 3: All changes to GCC are surrounded by `#ifdef GPC ..
     #endif', so they should not interfere when you build a C compiler
     from this source tree.

     It is possible, though not required, to build the compiler in a
     directory other than the one containing the sources.  (If you do
     that, you do not need to write into the GCC source directory and
     can build GPC for more than one platform from the same source
     tree.)  In that case, you need a `make' that understands the VPATH
     variable.  GNU make does, although at least GNU make version 3.71
     has a bug in the way it treats VPATH.  GNU make version 3.75 is
     known to work.

     If you have built GNU Pascal previously in the same directory for a
     different target machine, do `make distclean' to delete all files
     that might be invalid.  One of the files this deletes is
     `Makefile'; if `make distclean' complains that `Makefile' does not
     exist, it probably means that the directory is already suitably
     clean.

  2. Configuring and building GNU CC GNU Pascal is automatically
     configured with GNU CC.  Configuration of GNU CC is treated in
     depth in *Note the GCC installation instructions:
     (gcc)Installation.

     Chdir to the GCC object directory.  (This can be a directory of
     your choice, including the GCC source directory.)  From there, run
     the `configure' script in the GCC source directory.  If both
     directories are the same, the command

          % ./configure

     is sufficient to configure GCC in most cases.  If they are
     different, something like

          % ../gcc-2.8.1/configure

     will do the job.  This creates all the necessary config files,
     links and Makefile in the GCC object directory.

  3. The standard directory for installing GNU CC and GNU Pascal is
     `/usr/local/lib'.  If you want to install its files somewhere else,
     specify `--prefix=DIR' when you run `configure'.  Here DIR is a
     directory name to use instead of `/usr/local' for all purposes
     with one exception: the directory `/usr/local/include' is searched
     for header files no matter where you install the compiler.  To
     override this name, use the `--local-prefix' option below.

  4. Specify `--local-prefix=DIR' if you want the compiler to search
     directory `DIR/include' for locally installed header files
     *instead* of `/usr/local/include'.

     You should specify `--local-prefix' *only* if your site has a
     different convention (not `/usr/local') for where to put
     site-specific files.

     *Do not* specify `/usr' as the `--local-prefix'!  The directory
     you use for `--local-prefix' *must not* contain any of the
     system's standard header files.  If it did contain them, certain
     programs would be miscompiled (including GNU Emacs, on certain
     targets), because this would override and nullify the header file
     corrections made by the `fixincludes' script.

  5. Make sure the Bison parser generator is installed.  (This is
     unnecessary if the Bison output files `c-parse.c', `cexp.c', and
     `p/parse.y' are more recent than `c-parse.y', `cexp.y',
     `p/parse.c', and `p/parse.h' and you do not plan to change the
     `.y' files.)

     Bison versions older than Sept 8, 1988 will produce incorrect
     output for `c-parse.c'.

  6. If you have chosen a configuration for GNU Pascal which requires
     other GNU tools (such as GAS or the GNU linker) instead of the
     standard system tools, install the required tools in the build
     directory under the names `as', `ld' or whatever is appropriate.
     This will enable the compiler to find the proper tools for
     compilation of the program `enquire'.

     Alternatively, you can do subsequent compilation using a value of
     the `PATH' environment variable such that the necessary GNU tools
     come before the standard system tools.

  7. Once you are satisfied with the configuration as determined by
     `configure', you can build the Pascal compiler:

          % make LANGUAGES=pascal

     (Just `make' would also build the C++ and Objective C compilers).
     Notice that this procedure will build the C compiler too, because
     that is used to compile the GPC runtime library.

     Optionally, you may supply CFLAGS, LDFLAGS or RTSFLAGS. CFLAGS is
     used for compiler and RTS, RTSFLAGS are for RTS only, i.e.: `make
     CFLAGS="-O2" RTSFLAGS=-Wall'

  8. When everything compiles, you can verify what the `make -n
     pascal.install' command does, and if you are satisfied run it
     without the `-n' option to install the compiler `gpc1', front end
     `gpc', run time system `libgpc.a' to the same place where `gcc'
     was installed. This installation process does *not* overwrite
     existing copies of `libgcc.a' or `specs', should they exist.

     You can also install GPC as part of the complete GNU compiler
     suite using "make install" as described in the GCC installation
     docs.



File: gpc.info,  Node: compilation notes,  Next: cross-compilers,  Up: Installation

Configuration dependent compilation notes
=========================================

* Menu:

* Alpha OSF/1::      Installation on an Alpha OSF/1 system.
* MS-DOS: DJGPP.     The DJGPP port of GNU compilers to MS-DOS.
* MS-DOS, OS/2: EMX. The EMX port of GNU compilers to MS-DOS and OS/2.
* Windows 95/NT::    Installation on a Windows 95/NT system.


File: gpc.info,  Node: Alpha OSF/1,  Next: DJGPP,  Up: compilation notes

Alpha OSF/1
-----------

   For alpha OSF/1 v3.2 (GCC 2.6.3): If your linker starts to output
error messages like:

     Warning: Linking some objects which contain exception information sections
         and some which do not. This may cause fatal runtime exception handling
         problems (last obj encountered without exceptions was <OBJ/LIB>)

   We do not know why these started to appear, but you can get rid of
these if you do as follows in the GPC object directory.

   You need to trigger the Makefile dependencies, e.g. by doing the
touch command below. What happens is that it re-generates the
`version.c' and `rts/version.c' files, which need to be recompiled with
`ALPHA_BUG' defined.

   Example:
     % touch Makefile
     % make MY_CFLAGS=-DALPHA_BUG other-make-flags-you-want-to-use


File: gpc.info,  Node: DJGPP,  Next: EMX,  Prev: Alpha OSF/1,  Up: compilation notes

MS-DOS with DJGPP
-----------------

   You cannot build GNU CC (or GNU Pascal) by itself on MS-DOS or a
compatible system; it will not compile under any MS-DOS compiler except
itself.  The official MS-DOS port of GCC is called DJGPP, and it is
available from `simtel.coast.net' and it has mirrors all over the world.
The `configure' script is replaced by an MS-DOS batch file called
`configure.bat' wich does essentially the same. Detailed instructions
are in the file `config/msdos/README.dj' of the GNU Pascal source
distribution.


File: gpc.info,  Node: EMX,  Next: Windows 95/NT,  Prev: DJGPP,  Up: compilation notes

MS-DOS or OS/2 with EMX
-----------------------

   EMX is a free 32-bit DOS extender which adds some properties of UNIX
to MS-compatible DOS and IBM's OS/2 operating systems.  You can find
it, for example, via anonymous `ftp' on the server
`ftp.uni-stuttgart.de' in the directory `pub/systems/os2/emx*'.

   Due to the limitation of the command line to 128 characters we don't
know a way to compile GPC for EMX under DOS; you need OS/2 instead.  If
you succeed to compile GPC for EMX on a DOS system, please let us know.
(However you can compile GPC for DJGPP on a DOS system.)

   To compile under OS/2 you need EMX 0.9d and the patched source files
for GCC 2.8.1.  The sources assume that the system will be compiled on
an HPFS filesystem although the Makefiles can be easily modified for
FAT16.  The GCC backend requires dmake 3.8 to compile whereas the GPC
parts of the systems are compiled with GNU Make 3.7 or later.

  1. Unzip the source for GCC from the root directory, and rename the
     resulting directory `gcc-2.8' to `gpc'.
            cd \
            unzip c:\gccsrc1
            unzip c:\gccsrc2
            unzip c:\gccsrc3
            ren \emx\gnu\gcc-2.8 gpc

  2. Unpack the source for GPC from the `emx\gnu' directory, so it will
     go into the gpc subdirectory.  Unlike other EMX sources, the GPC
     source must *not* be extracted from the root directory.
            cd \emx\gnu
            unzip c:\gpc-21s.zip

  3. If you are working on a drive different from `d:' and/or if you
     want to compile the compiler with optimization and/or without
     debugging information (recommended), edit
     `\emx\gnu\gpc\dostage1.cmd' to refer to your drive and to have the
     `CFLAGS' you want, e.g.  `CFLAGS="-g -O2"' instead of `CFLAGS=-g'.

  4. You will also want to apply the patches for gcc.  To do this you
     will need GNU Patch (also known as Larry Wall's Patch), which
     should be available from the normal OS/2 `ftp' archives, e.g.
     `hobbes.nmsu.edu' in the `/pub/os2/unix/dev' directory.  Make sure
     you rename `patch.exe' to a filename that won't conflict with the
     built in OS/2 `patch' command.  EM recommends using `lwpatch.exe'
     in his `\emx\doc\build.doc' file.

     Apply the diff:
            cd \emx\gnu\gpc
            set emxopt=-t
            lwpatch --prefix=~ < p\diffs\gcc-2.8.1.diff
            set emxopt=

  5. Compile GPC using the `compile.cmd' script.
            cd \emx\gnu\gpc\p
            compile

  6. To install, move the GPC files into place.
            cd \emx\gnu\gpc
            copy gpc*.exe \emx\bin
            copy gpc.a \emx\lib



File: gpc.info,  Node: Windows 95/NT,  Prev: EMX,  Up: compilation notes

Windows NT and Windows 95 with cygwin32
---------------------------------------

   cygwin32 is a project to make it easy to port UNIX applications to
machines which run an OS which supports the Win32 API--i.e. Microsoft
Windows 95 and Windows NT. Currently, cygwin32 is in beta stage; it is
available from `ftp://ftp.cygnus.com/pub/gnu-win32/' Don't use gcc
sources from the cygwin32 distribution. These are not just modified from
FSF `gcc-2.8.1' to support the Windows 95/NT target, they are the
"current development release", and too different from FSF GCC to be
compatible with GNU Pascal, which is based on FSF sources.

   Currently, cygwin32 is not self-hosting: the preferred way to build
the cygwin32-gpc binary is to use a UNIX system with a cygwin32
targeting cross-compiler. *Note Crossbuilding::


File: gpc.info,  Node: cross-compilers,  Next: binary distributions,  Prev: compilation notes,  Up: Installation

Building and Installing a cross-compiler
========================================

   GNU Pascal can function as a cross-compiler for many machines, but
not all.  Also, only a few combinations have been tested. If you need
information about GNU tools in a cross-configuration,
`ftp://ftp.cygnus.com/pub/embedded/crossgcc/' is the place to be.

   * Cross-compilers for the Mips as target using the Mips assembler
     currently do not work, because the auxiliary programs
     `mips-tdump.c' and `mips-tfile.c' can't be compiled on anything
     but a Mips.  It does work to cross compile for a Mips if you use
     the GNU assembler and linker.

   * Cross-compilers between machines with different floating point
     formats have not all been made to work.  GNU C now has a floating
     point emulator with which these can work, but each target machine
     description needs to be updated to take advantage of it.

   * Cross-compilation between machines of different word sizes is
     somewhat problematic and sometimes does not work.

   Since GNU Pascal generates assembler code, you probably need a
cross-assembler that GNU Pascal can run, in order to produce object
files.  If you want to link on other than the target machine, you need a
cross-linker as well.  You also need header files and libraries suitable
for the target machine that you can install on the host machine.

* Menu:

* Steps of Cross::      Using a cross-compiler involves several steps
                        that may be carried out on different machines.
* Configure Cross::     Configuring a cross-compiler.
* Build Cross::         Actually building a Pascal cross-compiler.
* Crossbuilding::	Crossbuilding a Pascal compiler.


File: gpc.info,  Node: Steps of Cross,  Next: Configure Cross,  Up: cross-compilers

Steps of Cross-Compilation
--------------------------

   To compile and run a program using a cross-compiler involves several
steps:

   * Run the cross-compiler on the host machine to produce assembler
     files for the target machine.  This requires header files for the
     target machine.

   * Assemble the files produced by the cross-compiler.  You can do this
     either with an assembler on the target machine, or with a
     cross-assembler on the host machine.

   * Link those files to make an executable.  You can do this either
     with a linker on the target machine, or with a cross-linker on the
     host machine.  Whichever machine you use, you need libraries and
     certain startup files (typically `crt....o') for the target
     machine.

   It is most convenient to do all of these steps on the same host
machine, since then you can do it all with a single invocation of GNU
Pascal.  This requires a suitable cross-assembler and cross-linker.
For some targets, the GNU assembler and linker are available.


File: gpc.info,  Node: Configure Cross,  Next: Build Cross,  Prev: Steps of Cross,  Up: cross-compilers

Configuring GNU CC as a cross-compiler
--------------------------------------

   No special actions have to be taken to configure GNU Pascal as a
cross-compiler. Cross-compiler specific configuration is done only for
GCC.  Section 4.2 of "Using and Porting GNU CC" deals with
cross-configurations in great detail. Once cross-binutils and a C
library for the target machine are in place, GCC can be configured
(from the GCC object directory).  Suppose we are on a FreeBSD system
and want a cross-compiler that produces code that runs on MS-DOS:

     % ../gcc-2.8.1/configure --prefix=/usr --target=i386-go32

   This creates all the necessary config files, links and Makefile in
the GCC object directory. Now, proceed with the compilation and
installation process like in the case of the native configuration
described before. Do not remove files from the GCC object directory;
the cross-compiler is used to compile the GNU Pascal runtime system
(RTS) for the target system.


File: gpc.info,  Node: Build Cross,  Next: Crossbuilding,  Prev: Configure Cross,  Up: cross-compilers

Building the Pascal cross-compiler
----------------------------------

   Once you have verified the C cross-compiler, the Pascal
cross-compiler can be configured and built. Note that the `configure'
script does not require any cross-compiler related switches because GPC
inherits all of this from GNU CC.

   Sample output for a FreeBSD->msdos cross configuration:

     --------------------------------------------------------------------------
     Configuration summary:
       Building a i386-go32 cross-compiler hosted by i386-unknown-freebsd2.1.0
     
       GPC sources in:         ../gpc-2.0
       GCC sources in:         ../gcc-2.8.1
       GCC object code in:     ../gcc
       GCC version:            2.8.1
     
       Compiler for GPC:       gcc
       Compiler for libgpc.a:  i386-go32-gcc
       Compiler flags:         -g -O
     
       Cross-ar utility:       i386-go32-ar
       Cross-ranlib utility:   i386-go32-ranlib
     
       Installation path:      /usr/bin, /usr/lib/gcc-lib/i386-go32/2.8.1
     --------------------------------------------------------------------------
     
     Now, type `make' to build the compiler and runtime system.

   Building a cross-compiler requires cross-binutils for your target,
i386-go32 in this examples. If `configure' is not able to find
`i386-go32-ar' and/or `i386-go32-ranlib', you may have to run it again
with again with `--with-ar=YOUR-CROSS-AR' or
`--with-ranlib=YOUR-CROSS-RANLIB' switches.

   Then, `make' and `make install' the cross-compiler like you would
for a native configuration.


File: gpc.info,  Node: Crossbuilding,  Prev: Build Cross,  Up: cross-compilers

Crossbuilding a compiler.
-------------------------

   Yet another possibility is CROSSBUILDING : Using a cross-compiler to
build GNU Pascal results in a compiler binary that runs on the
cross-target platform. A possible reason why anybody would want to do
this, is when the platform on which you want to run the GNU Pascal
compiler, is not self-hosting. An example is cygwin32.

   To crossbuild GNU Pascal, you have to install a cross-compiler for
your target first. This is covered in chapter 4 of "Using and Porting
GNU CC".  Assuming you want to build a native cygwin32 Pascal compiler
on a FreeBSD system, configure GCC:

     % ../gcc-2.8.1/configure --prefix=/usr --build=i386-freebsd \
     	--host=i386-cygwin32 --target=i386-cygwin32

   Build it:

     % make CFLAGS=-O2 LANGUAGES=c

   Now, configure and build GPC. The output of `configure' should look
like:

     --------------------------------------------------------------------------
     Configuration summary:
       Building a i386-cygwin32 cross-compiler hosted by i386-cygwin32
     
       GPC sources in:         ../gpc-2.0
       GCC sources in:         ../gcc-2.8.1
       GCC object code in:     ../gcc
       GCC version:            2.8.1
     
       Compiler for GPC:       i386-cygwin32-gcc
       Compiler for libgpc.a:  i386-cygwin32-gcc
       Compiler flags:         -g -O
     
       Cross-ar utility:       i386-cygwin32-ar
       Cross-ranlib utility:   i386-cygwin32-ranlib
     
       Installation path:      /usr/bin, /usr/lib/gcc-lib/i386-cygwin32/2.8.1
     --------------------------------------------------------------------------
     
     Now, type `make' to build the compiler and runtime system.

   Again, `configure' should be able to detect and configure this setup
without additional flags. If not, specify `--with-ar', `--with-ranlib',
`--with-gcc' and/or `--with-rtsgcc' as appropriate.

   A cross-built compiler must be installed by hand.


File: gpc.info,  Node: binary distributions,  Prev: cross-compilers,  Up: Installation

Installation instructions for a GPC binary distribution
=======================================================

   To install a binary distribution, cd to the main directory and
unpack the archive while preserving the stored directory structure.  In
concrete, to install a ZIP archive under DOS with PKunzip, `cd' the the
appropriate directory (usually `\' for EMX, `\DJGPP' for DJGPP), then
type

       C:\> pkunzip -d ARCHIVE

   where ARCHIVE is the name of the distribution file.  To install a
`.tar.gz' archive under a UNIX compatible system, become root, then
extract the archive from the root of the filesystem:

       # tar xzf ARCHIVE.tar.gz

   If you are using a `tar' utility other than GNU tar, it might be
necessary to do the above in two steps:

       # gzip -d ARCHIVE.tar.gz
       # tar xf ARCHIVE.tar

   Binary distributions include `libgcc.a' and `specs', files that are
normally part of GCC.  If you have GCC installed, they will be replaced
unless you manually install the archive.


File: gpc.info,  Node: Invoking GPC,  Next: Programming,  Prev: Installation,  Up: Top

GNU Pascal Command Options
**************************

   GPC is a command-line compiler, i.e. to compile a program you have
to invoke `gpc' passing it the name of the file you want to compile,
plus options.

   Typing

     gpc foo.pas

   means to compile the source file `foo.pas' and to produce an
executable of the default name which is `foo.exe' on EMX, `a.exe' on
DJGPP, and `a.out' on most other platforms.

   A more typical example reads

     gpc -O --automake foo.pas -o foo

   This means to compile the source file `foo.pas' to an executable
named `foo' (that's the meaning of the `-o' option) with optimization
(the `-O' option).  When the program uses Units or imports Modules, they
will be automatically compiled and linked (the `--automake' option).

   The following gives a detailed description of all options accepted by
`gpc'.  While there are really a lot of options, you will need only a
few of them, so don't worry.  ;-)  Most options are there to customize
GPC's behaviour in order to satisfy a large variety of users on a large
variety of platforms.

   When you invoke GPC, it normally does preprocessing, compilation,
assembly and linking.  The "overall options" allow you to stop this
process at an intermediate stage.  For example, the `-c' option says
not to run the linker.  Then the output consists of object files output
by the assembler.

   Other options are passed on to one stage of processing.  Some options
control the preprocessor and others the compiler itself.  Yet other
options control the assembler and linker; most of these are not
documented here, since you rarely need to use any of them.

   The `gpc' program accepts options and file names as operands.  Many
options have multiletter names; therefore multiple single-letter options
may *not* be grouped: `-dr' is very different from `-d -r'.

   You can mix options and other arguments.  For the most part, the
order you use doesn't matter.  Order does matter when you use several
options of the same kind; for example, if you specify `-L' more than
once, the directories are searched in the order specified.

   Many options have long names starting with `-f' or with `-W'--for
example, `-fforce-mem', `-fstrength-reduce', `-Wformat' and so on.
Most of these have both positive and negative forms; the negative form
of `-ffoo' would be `-fno-foo'.  This manual documents only one of
these two forms, whichever one is not the default.

* Menu:

* Option Summary::   	   Brief list of all options, without explanations.
* Overall Options::        Controlling the kind of output:
                           an executable, object files, assembler files,
                           or preprocessed source.
* Pascal Dialect Options:: Controlling the variant of Pascal language compiled.
* Code Gen Options::       Specifying conventions for function calls, data
                           layout and register usage.
* Warning Options::        How picky should the compiler be?
* Debugging Options::      Symbol tables, measurements, and debugging dumps.
* Optimize Options::       How much optimization?
* Preprocessor Options::   Controlling header files and macro definitions.
                           Also, getting dependency information for Make.
* Assembler Options::      Passing options to the assembler.
* Link Options::           Specifying libraries and so on.
* Directory Options::      Where to find header files and libraries.
                           Where to find the compiler executable files.
* Target Options::         Running a cross-compiler, or an old version
                           of GNU Pascal.
* Submodel Options::       Specifying minor hardware or convention variations,
                           such as 68010 vs 68020.
* Environment Variables::  Env vars that affect GNU Pascal.


File: gpc.info,  Node: Option Summary,  Next: Overall Options,  Up: Invoking GPC

Option Summary
==============

   Here is a summary of all the options, grouped by type.  Explanations
are in the following sections.

*Overall Options*
     *Note Options Controlling the Kind of Output: Overall Options.
          -c  --automake  -S  -E  -o FILE  -pipe  -v  -x LANGUAGE

*Pascal Language Options*
     *Note Options Controlling Pascal Dialect: Pascal Dialect Options.
          --nested-comments --char-escapes --c-numbers --borland-char-constants
          --standard-pascal --extended-pascal --object-pascal --borland-pascal
          --pascal-sc --extended-syntax

*Code Generation Options*
     *Note Options for Code Generation Conventions: Code Gen Options.
          --short-circuit --lazy-io --setlimit --gpc-main
          --call-saved-REG  --call-used-REG
          --fixed-REG  --inhibit-size-directive
          --no-common  --no-ident  --no-gnu-linker
          --pcc-struct-return  --pic  --PIC
          --reg-struct-return  --shared-data  --short-enums
          --short-double  --volatile  --volatile-global
          --verbose-asm --pack-struct

*Warning Options*
     *Note Options to Request or Suppress Warnings: Warning Options.
          --syntax-only  --pedantic  --pedantic-errors
          -w  -W  -Wall  -Waggregate-return  -Wbad-function-cast
          -Wcast-align -Wcast-qual  -Wchar-subscript  -Wcomment
          -Wconversion -Wenum-clash  -Werror  -Wformat
          -Wid-clash-LEN  -Wimplicit  -Wimport  -Winline
          -Wlarger-than-LEN  -Wmissing-declarations
          -Wmissing-prototypes  -Wnested-externs
          -Wno-import  -Woverloaded-virtual -Wparentheses
          -Wpointer-arith  -Wredundant-decls -Wreorder -Wreturn-type -Wshadow
          -Wstrict-prototypes  -Wswitch  -Wsynth  -Wtemplate-debugging
          -Wtraditional  -Wtrigraphs -Wuninitialized  -Wunused
          -Wwrite-strings

*Debugging Options*
     *Note Options for Debugging Your Program or GPC: Debugging Options.
          -a  -dLETTERS  -fpretend-float
          -g  -gLEVEL -gcoff  -gdwarf  -gdwarf+
          -ggdb  -gstabs  -gstabs+  -gxcoff  -gxcoff+
          -p  -pg  -print-file-name=LIBRARY  -print-libgcc-file-name
          -print-prog-name=PROGRAM  -print-search-dirs  -save-temps
          --lines  --debug-gpi

*Optimization Options*
     *Note Options that Control Optimization: Optimize Options.
          --caller-saves  --cse-follow-jumps  --cse-skip-blocks
          --delayed-branch   --expensive-optimizations
          --fast-math  --float-store  --force-addr  --force-mem
          --inline-functions  --keep-inline-functions
          --no-default-inline  --no-defer-pop  --no-function-cse
          --no-inline  --no-peephole  --omit-frame-pointer
          --rerun-cse-after-loop  --schedule-insns
          --schedule-insns2  --strength-reduce  --thread-jumps
          --unroll-all-loops  --unroll-loops
          -O  -O0  -O1  -O2  -O3

*Preprocessor Options*
     *Note Options Controlling the Preprocessor: Preprocessor Options.
          -AQUESTION(ANSWER)  -C  -dD  -dM  -dN
          -DMACRO[=DEFN]  -E  -H
          -idirafter DIR
          -include FILE  -imacros FILE
          -iprefix FILE  -iwithprefix DIR
          -iwithprefixbefore DIR  -isystem DIR
          -M  -MD  -MM  -MMD  -MG  -nostdinc  -P  -trigraphs
          -undef  -UMACRO  -Wp,OPTION

*Assembler Option*
     *Note Passing Options to the Assembler: Assembler Options.
          -Wa,OPTION

*Linker Options*
     *Note Options for Linking: Link Options.
          OBJECT-FILE-NAME  -lLIBRARY
          -nostartfiles  -nodefaultlibs  -nostdlib
          -s  -static  -shared  -symbolic
          -Wl,OPTION  -Xlinker OPTION
          -u SYMBOL

*Directory Options*
     *Note Options for Directory Search: Directory Options.
          -BPREFIX  -IDIR  -I-  -LDIR

*Target Options*
     *Note Target Options::.
          -b MACHINE  -V VERSION

*Machine Dependent Options*
     *Note Hardware Models and Configurations: Submodel Options.
          *M680x0 Options*
          -m68000  -m68020  -m68020-40  -m68030  -m68040  -m68881
          -mbitfield  -mc68000  -mc68020  -mfpa  -mnobitfield
          -mrtd  -mshort  -msoft-float
          
          *VAX Options*
          -mg  -mgnu  -munix
          
          *SPARC Options*
          -mapp-regs  -mcypress  -mepilogue  -mflat  -mfpu  -mhard-float
          -mhard-quad-float  -mno-app-regs  -mno-flat  -mno-fpu
          -mno-epilogue  -mno-unaligned-doubles
          -msoft-float  -msoft-quad-float
          -msparclite  -msupersparc  -munaligned-doubles  -mv8
          
          SPARC V9 compilers support the following options
          in addition to the above:
          
          -mmedlow  -mmedany
          -mint32  -mint64  -mlong32  -mlong64
          -mno-stack-bias  -mstack-bias
          
          *Convex Options*
          -mc1  -mc2  -mc32  -mc34  -mc38
          -margcount  -mnoargcount
          -mlong32  -mlong64
          -mvolatile-cache  -mvolatile-nocache
          
          *AMD29K Options*
          -m29000  -m29050  -mbw  -mnbw  -mdw  -mndw
          -mlarge  -mnormal  -msmall
          -mkernel-registers  -mno-reuse-arg-regs
          -mno-stack-check  -mno-storem-bug
          -mreuse-arg-regs  -msoft-float  -mstack-check
          -mstorem-bug  -muser-registers
          
          *ARM Options*
          -mapcs -m2 -m3 -m6 -mbsd -mxopen -mno-symrename
          
          *M88K Options*
          -m88000  -m88100  -m88110  -mbig-pic
          -mcheck-zero-division  -mhandle-large-shift
          -midentify-revision  -mno-check-zero-division
          -mno-ocs-debug-info  -mno-ocs-frame-position
          -mno-optimize-arg-area  -mno-serialize-volatile
          -mno-underscores  -mocs-debug-info
          -mocs-frame-position  -moptimize-arg-area
          -mserialize-volatile  -mshort-data-NUM  -msvr3
          -msvr4  -mtrap-large-shift  -muse-div-instruction
          -mversion-03.00  -mwarn-passed-structs
          
          *RS/6000 and PowerPC Options*
          -mcpu=CPU  TYPE
          -mpower  -mno-power  -mpower2  -mno-power2
          -mpowerpc  -mno-powerpc
          -mpowerpc-gpopt  -mno-powerpc-gpopt
          -mpowerpc-gfxopt  -mno-powerpc-gfxopt
          -mnew-mnemonics  -mno-new-mnemonics
          -mfull-toc   -mminimal-toc  -mno-fop-in-toc  -mno-sum-in-toc
          -msoft-float  -mhard-float -mmultiple -mno-multiple
          -mstring -mno-string -mbit-align -mno-bit-align
          -mstrict-align -mno-strict-align -mrelocatable -mno-relocatable
          -mtoc -mno-toc -mtraceback -mno-traceback
          -mlittle -mlittle-endian -mbig -mbig-endian
          -mcall-aix -mcall-sysv -mprototype
          
          *RT Options*
          -mcall-lib-mul  -mfp-arg-in-fpregs  -mfp-arg-in-gregs
          -mfull-fp-blocks  -mhc-struct-return  -min-line-mul
          -mminimum-fp-blocks  -mnohc-struct-return
          
          *MIPS Options*
          -mabicalls  -mcpu=CPU  TYPE  -membedded-data
          -membedded-pic  -mfp32  -mfp64  -mgas  -mgp32  -mgp64
          -mgpopt  -mhalf-pic  -mhard-float  -mint64 -mips1
          -mips2 -mips3  -mlong64  -mlong-calls  -mmemcpy
          -mmips-as  -mmips-tfile  -mno-abicalls
          -mno-embedded-data  -mno-embedded-pic
          -mno-gpopt  -mno-long-calls
          -mno-memcpy  -mno-mips-tfile  -mno-rnames  -mno-stats
          -mrnames -msoft-float
          -m4650 -msingle-float -mmad
          -mstats  -EL  -EB  -G NUM  -nocpp
          
          *i386 Options*
          -m486  -m386 -mieee-fp  -mno-fancy-math-387
          -mno-fp-ret-in-387  -msoft-float  -msvr3-shlib
          -mno-wide-multiply -mrtd -malign-double
          -mreg-alloc=LIST -mregparm=NUM
          -malign-jumps=NUM -malign-loops=NUM
          -malign-functions=NUM
          
          *HPPA Options*
          -mdisable-fpregs  -mdisable-indexing  -mfast-indirect-calls
          -mgas  -mjump-in-delay -mlong-millicode-calls -mno-disable-fpregs
          -mno-disable-indexing -mno-fast-indirect-calls -mno-gas
          -mno-jump-in-delay -mno-millicode-long-calls
          -mno-portable-runtime -mno-soft-float -msoft-float
          -mpa-risc-1-0  -mpa-risc-1-1  -mportable-runtime -mschedule=LIST
          
          *Intel 960 Options*
          -mCPU TYPE  -masm-compat  -mclean-linkage
          -mcode-align  -mcomplex-addr  -mleaf-procedures
          -mic-compat  -mic2.0-compat  -mic3.0-compat
          -mintel-asm  -mno-clean-linkage  -mno-code-align
          -mno-complex-addr  -mno-leaf-procedures
          -mno-old-align  -mno-strict-align  -mno-tail-call
          -mnumerics  -mold-align  -msoft-float  -mstrict-align
          -mtail-call
          
          *DEC Alpha Options*
          -mfp-regs  -mno-fp-regs  -mno-soft-float
          -msoft-float
          
          *Clipper Options*
          -mc300 -mc400
          
          *H8/300 Options*
          -mrelax  -mh
          
          *System V Options*
          -Qy  -Qn  -YP,PATHS  -Ym,DIR

* Menu:

* Overall Options::        Controlling the kind of output:
                           an executable, object files, assembler files,
                           or preprocessed source.
* Pascal Dialect Options:: Controlling the variant of Pascal language compiled.
* Code Gen Options::       Specifying conventions for function calls, data
                           layout and register usage.
* Warning Options::        How picky should the compiler be?
* Debugging Options::      Symbol tables, measurements, and debugging dumps.
* Optimize Options::       How much optimization?
* Preprocessor Options::   Controlling header files and macro definitions.
                           Also, getting dependency information for Make.
* Assembler Options::      Passing options to the assembler.
* Link Options::           Specifying libraries and so on.
* Directory Options::      Where to find header files and libraries.
                           Where to find the compiler executable files.
* Target Options::         Running a cross-compiler, or an old version
                           of GNU Pascal.
* Submodel Options::       Specifying minor hardware or convention variations,
                           such as 68010 vs 68020.
* Environment Variables::  Env vars that affect GNU Pascal.


File: gpc.info,  Node: Overall Options,  Next: Pascal Dialect Options,  Prev: Option Summary,  Up: Invoking GPC

Options Controlling the Kind of Output
======================================

   Compilation can involve up to four stages: preprocessing, compilation
proper, assembly and linking, always in that order.  The first three
stages apply to an individual source file, and end by producing an
object file; linking combines all the object files (those newly
compiled, and those specified as input) into an executable file.

   For any given input file, the file name suffix determines what kind
of compilation is done:

`FILE.p'
`FILE.pas'
     Pascal source code which must be preprocessed.

`FILE.i'
     Pascal source code which should not be preprocessed.

`FILE.h'
     Pascal header file (not to be compiled or linked).

`FILE.s'
     Assembler code.

`FILE.S'
     Assembler code which must be preprocessed.

`OTHER'
     An object file to be fed straight into linking.  Any file name
     with no recognized suffix is treated this way.

   You can specify the input language explicitly with the `-x' option:

`-x LANGUAGE'
     Specify explicitly the LANGUAGE for the following input files
     (rather than letting the compiler choose a default based on the
     file name suffix).  This option applies to all following input
     files until the next `-x' option.  Possible values for LANGUAGE
     are:
          pascal   c  objective-c  c++
          c-header  cpp-output  c++-cpp-output
          assembler  assembler-with-cpp

`-x none'
     Turn off any specification of a language, so that subsequent files
     are handled according to their file name suffixes (as they are if
     `-x' has not been used at all).

   If you only want some of the stages of compilation, you can use `-x'
(or filename suffixes) to tell `gcc' where to start, and one of the
options `-c', `-S', or `-E' to say where `gpc' is to stop.  Note that
some combinations (for example, `-x cpp-output -E' instruct `gpc' to do
nothing at all.

`-c'
     Compile or assemble the source files, but do not link.  The linking
     stage simply is not done.  The ultimate output is in the form of an
     object file for each source file.

     By default, the object file name for a source file is made by
     replacing the suffix `.p', `.pas', `.i', `.s', etc., with `.o'.

     Unrecognized input files, not requiring compilation or assembly,
     are ignored.

`--automake'
     Check whether Modules/Units used by the main program must be
     recompiled and do the recompilation.  For example, if the program
     `mainprog.pas' uses the Modules `module1.pas' and `module2.pas',
     the modules are automatically compiled if necessary when you
     specify
            gpc --automake mainprog.pas

     Options to be passed to "child" compilations must be given
     explicitely as a "String" argument to -automake, for example:
            gpc -O --automake mainprog.pas

     (For an explanation of the -O option, see *Note Optimize
     Options::.)

     *WARNING:* The AutoMake mechanism is a new feature in version 2.0
     and may be unstable.

`-S'
     Stop after the stage of compilation proper; do not assemble.  The
     output is in the form of an assembler code file for each
     non-assembler input file specified.

     By default, the assembler file name for a source file is made by
     replacing the suffix `.p', `.pas', `.i', etc., with `.s'.

     Input files that don't require compilation are ignored.

`-E'
     Stop after the preprocessing stage; do not run the compiler
     proper.  The output is in the form of preprocessed source code,
     which is sent to the standard output.

     Input files which don't require preprocessing are ignored.

`-o FILE'
     Place output in file FILE.  This applies regardless to whatever
     sort of output is being produced, whether it be an executable file,
     an object file, an assembler file or preprocessed C code.

     Since only one output file can be specified, it does not make
     sense to use `-o' when compiling more than one input file, unless
     you are producing an executable file as output.

     If `-o' is not specified, the default is to put an executable file
     in `a.out', the object file for `SOURCE.SUFFIX' in `SOURCE.o', its
     assembler file in `SOURCE.s', and all preprocessed C source on
     standard output.

`-v'
     Print (on standard error output) the commands executed to run the
     stages of compilation.  Also print the version number of the
     compiler driver program and of the preprocessor and the compiler
     proper.

`-pipe'
     Use pipes rather than temporary files for communication between the
     various stages of compilation.  This fails to work on some systems
     where the assembler is unable to read from a pipe; but the GNU
     assembler has no trouble.


File: gpc.info,  Node: Pascal Dialect Options,  Next: Code Gen Options,  Prev: Overall Options,  Up: Invoking GPC

Options Controlling Pascal Dialect
==================================

   GNU Pascal tries to support several different Pascal dialects.  Some
features of some dialects contradict each other, some other "features"
we do not consider to be a good idea.  To achive compatibility to all
dialects (in as much as currently implemented), a number of options is
provided.

`--standard-pascal-level-0'
`--standard-pascal'
`--extended-pascal'
`--object-pascal'
`--borland-pascal'
`--pascal-sc'
     These switches tell `gpc' to comply to the specified standard.
     Keywords coming from other dialects are not recognized and can be
     redefined without warning.  The use of other extensions triggers a
     warning; other warnings about constructs which would be legal in
     the specified dialect (e.g. assignment to a Borland-style "typed
     constant") are suppressed.

     By default, GNU Pascal allows redefinition of keywords.  Each of
     this switches causes GNU Pascal to forbid the redefinition of
     keywords of the specified standard.

     Valid ISO Standard Pascal programs should compile properly with or
     without `--standard-pascal'.  However, without this option,
     certain GNU extensions and Pascal features from other dialects are
     supported as well.  With this option, they are rejected.

     This options are not intended to be useful; they exist only to
     satisfy pedants who would otherwise claim that GNU Pascal fails to
     support the ISO Standard or is not really compatible to Borland
     Pascal, or whatever.  We recommend, rather, that users take
     advantage of the extensions of GNU Pascal and disregard the
     limitations of other compilers.

`--extended-syntax  (*$X+*)'
     Enables "dangerous" features of GNU Pascal such as
        * function return value ignore (works always, but gives warning
          without         this option),

        * pointer arithmetics,

        * declaring statements (gives warning otherwise; see *Note
          Var::),

        * use of `CString's as strings (see *Note CString::).

     The compiler switch `$X+' is equivalent to `--extended-syntax' and
     allows local specifications.

     *A cross reference to compiler switches is in preparation.*

`--no-nested-comments  (*$N-*)'
     By default (unless full ISO compliance has been requested), GPC
     allows nested comments (* like this one { see? } *) in your Pascal
     source which contradicts ISO standard.  To allow comments starting
     with `{' and ending with `*)', specify this option.

`--char-escapes  (*$E+*)'
     Enable C-style character escape sequences in strings.

`--c-numbers  (*$C+*)'
     Enable C-style octal and hexadecimal numbers: The decimal number
     255 is equal to the hexadecimal number `16#FF' (Extended Pascal
     notation) or `$FF' (Borland Pascal notation) or `0xFF' (C
     notation--works only with this switch active) or the octal number
     `0177' (C notation--ditto).

`--borland-char-constants'
     Enable Borland-style `#42' character constants.  The default is
     "on" unless full ISO compliance has been selected using
     `--standard-pascal', `--extended-pascal', or `--object-pascal'.
     For those cases the default is "off".


File: gpc.info,  Node: Code Gen Options,  Next: Warning Options,  Prev: Pascal Dialect Options,  Up: Invoking GPC

Options for Code Generation Conventions
=======================================

   These machine-independent options control the interface conventions
used in code generation.

   Most of them have both positive and negative forms; the negative form
of `-ffoo' would be `-fno-foo'.  In the table below, only one of the
forms is listed--the one which is not the default.  You can figure out
the other form by either removing `no-' or adding it.

`--short-circuit  (*$B-*)'
     Use short circuit evaluation of Boolean expressions.  Otherwise,
     Boolean expressions are evaluated completely even if the result is
     kwown already.  The default is "on" unless full ISO compliance has
     been requested using `--standard-pascal', `--extended-pascal', or
     `--object-pascal'.  For those cases the default is "off".

`--lazy-io  (*$L+*)'
     Enable "lazy I/O", i.e. do a `put' as soon as you can and do `get'
     as late as you can.

`--setlimit:NUMBER'
     Define the maximum number of elements a set can hold to be NUMBER.

`--gpc-main:NAME'
     Name the entry point of the main program "NAME" instead of `main'.
     This is useful when working with some C libraries which define
     their own `main' function and require the program's "main" to be
     named differently.

`--pcc-struct-return'
     Return "short" `Record' values in memory like longer ones, rather
     than in registers.  This convention is less efficient, but it has
     the advantage of allowing intercallability between GNU
     Pascal-compiled files and files compiled with other compilers.

     The precise convention for returning records in memory depends on
     the target configuration macros.

     Short records are those whose size and alignment match that of some
     integer type.

`--reg-struct-return'
     Use the convention that `Record' values are returned in registers
     when possible.  This is more efficient for small records than
     `--pcc-struct-return'.

     If you specify neither `--pcc-struct-return' nor its contrary
     `--reg-struct-return', GNU Pascal defaults to whichever convention
     is standard for the target.  If there is no standard convention,
     GNU Pascal defaults to `--pcc-struct-return', except on targets
     where GNU Pascal is the principal compiler.  In those cases, we
     can choose the standard, and we chose the more efficient register
     return alternative.

`--short-enums'
     Allocate to enumeral types only as many bytes as it needs for the
     declared range of possible values.

`--short-double'
     Use a smaller size for `Real'.

`--shared-data'
     Requests that the data and non-`const' variables of this
     compilation be shared data rather than private data.  The
     distinction makes sense only on certain operating systems, where
     shared data is shared between processes running the same program,
     while private data exists in one copy per process.

`--no-common'
     Allocate even uninitialized global variables in the bss section of
     the object file, rather than generating them as common blocks.
     This has the effect that if the same variable is declared (without
     `external') in two different compilations, you will get an error
     when you link them.  The only reason this might be useful is if
     you wish to verify that the program will work on other systems
     which always work this way.

`--no-ident'
     Ignore the `#ident' directive.

`--no-gnu-linker'
     Do not output global initializations (such as C++ constructors and
     destructors) in the form used by the GNU linker (on systems where
     the GNU linker is the standard method of handling them).  Use this
     option when you want to use a non-GNU linker, which also requires
     using the `collect2' program to make sure the system linker
     includes constructors and destructors.  (`collect2' is included in
     the GNU GCC distribution.)  For systems which *must* use
     `collect2', the compiler driver `gpc' is configured to do this
     automatically.

`--inhibit-size-directive'
     Don't output a `.size' assembler directive, or anything else that
     would cause trouble if the function is split in the middle, and the
     two halves are placed at locations far apart in memory.  This
     option is used when compiling `crtstuff.c'; you should not need to
     use it for anything else.

`--verbose-asm'
     Put extra commentary information in the generated assembly code to
     make it more readable.  This option is generally only of use to
     those who actually need to read the generated assembly code
     (perhaps while debugging the compiler itself).

`--volatile'
     Consider all memory references through pointers to be volatile.

`--volatile-global'
     Consider all memory references to external and global data items to
     be volatile.

`--pic'
     Generate position-independent code (PIC) suitable for use in a
     shared library, if supported for the target machine.  Such code
     accesses all constant addresses through a global offset table
     (GOT).  If the GOT size for the linked executable exceeds a
     machine-specific maximum size, you get an error message from the
     linker indicating that `--pic' does not work; in that case,
     recompile with `--PIC' instead.  (These maximums are 16k on the
     m88k, 8k on the Sparc, and 32k on the m68k and RS/6000.  The 386
     has no such limit.)

     Position-independent code requires special support, and therefore
     works only on certain machines.  For the 386, GNU Pascal supports
     PIC for System V but not for the Sun 386i.  Code generated for the
     IBM RS/6000 is always position-independent.

     The GNU assembler does not fully support PIC.  Currently, you must
     use some other assembler in order for PIC to work.  We would
     welcome volunteers to upgrade GAS to handle this; the first part
     of the job is to figure out what the assembler must do differently.

`--PIC'
     If supported for the target machine, emit position-independent
     code, suitable for dynamic linking and avoiding any limit on the
     size of the global offset table.  This option makes a difference
     on the m68k, m88k and the Sparc.

     Position-independent code requires special support, and therefore
     works only on certain machines.

`--fixed-REG'
     Treat the register named REG as a fixed register; generated code
     should never refer to it (except perhaps as a stack pointer, frame
     pointer or in some other fixed role).

     REG must be the name of a register.  The register names accepted
     are machine-specific and are defined in the `REGISTER_NAMES' macro
     in the machine description macro file.

     This flag does not have a negative form, because it specifies a
     three-way choice.

`--call-used-REG'
     Treat the register named REG as an allocatable register that is
     clobbered by function calls.  It may be allocated for temporaries
     or variables that do not live across a call.  Functions compiled
     this way will not save and restore the register REG.

     Use of this flag for a register that has a fixed pervasive role in
     the machine's execution model, such as the stack pointer or frame
     pointer, will produce disastrous results.

     This flag does not have a negative form, because it specifies a
     three-way choice.

`--call-saved-REG'
     Treat the register named REG as an allocatable register saved by
     functions.  It may be allocated even for temporaries or variables
     that live across a call.  Functions compiled this way will save
     and restore the register REG if they use it.

     Use of this flag for a register that has a fixed pervasive role in
     the machine's execution model, such as the stack pointer or frame
     pointer, will produce disastrous results.

     A different sort of disaster will result from the use of this flag
     for a register in which function values may be returned.

     This flag does not have a negative form, because it specifies a
     three-way choice.

`--pack-struct'
     Pack all structure members together without holes.  Usually you
     would not want to use this option, since it makes the code
     suboptimal, and the offsets of structure members won't agree with
     system libraries.


File: gpc.info,  Node: Warning Options,  Next: Debugging Options,  Prev: Code Gen Options,  Up: Invoking GPC

Options to Request or Suppress Warnings
=======================================

   Warnings are diagnostic messages that report constructions which are
not inherently erroneous but which are risky or suggest there may have
been an error.

   You can request many specific warnings with options beginning `-W',
for example `-Wimplicit' to request warnings on implicit declarations.
Each of these specific warning options also has a negative form
beginning `-Wno-' to turn off warnings; for example, `-Wno-implicit'.
This manual lists only one of the two forms, whichever is not the
default.

   These options control the amount and kinds of warnings produced by
GNU Pascal:

   *GPC note: theses are all in toplev.c, but not all of them apply.*

`-fsyntax-only'
     Check the code for syntax errors, but don't do anything beyond
     that.

`-pedantic'
     Warn about everything which is known to be rejected in some Pascal
     dialect, for example redefinition of keywords of other dialects.

`-pedantic-errors'
     Produce errors rather than warnings for portability violations.
     Unlike in C, this does *not* imply the `-pedantic' option, so you
     can, for instance, use `-pedantic-errors' without `-pedantic', but
     with `--extended-pascal'.

`-w'
     Inhibit all warning messages.

`-Wno-import'
     Inhibit warning messages about the use of `#import'.

`-Wchar-subscripts'
     Warn if an array subscript has type `char'.  This is a common cause
     of error, as programmers often forget that this type is signed on
     some machines.

`-Wcomment'
     Warn whenever a comment-start sequence `/*' appears in a comment.

`-Wformat'
     Check calls to `printf' and `scanf', etc., to make sure that the
     arguments supplied have types appropriate to the format string
     specified.

`-Wimplicit'
     Warn whenever a function or parameter is implicitly declared.

`-Wparentheses'
     Warn if parentheses are omitted in certain contexts, such as when
     there is an assignment in a context where a truth value is
     expected, or when operators are nested whose precedence people
     often get confused about.

`-Wreturn-type'
     Warn whenever a function is defined with a return-type that
     defaults to `int'.  Also warn about any `return' statement with no
     return-value in a function whose return-type is not `void'.

`-Wswitch'
     Warn whenever a `switch' statement has an index of enumeral type
     and lacks a `case' for one or more of the named codes of that
     enumeration.  (The presence of a `default' label prevents this
     warning.)  `case' labels outside the enumeration range also
     provoke warnings when this option is used.

`-Wtrigraphs'
     Warn if any trigraphs are encountered (assuming they are enabled).

`-Wunused'
     Warn whenever a variable is unused aside from its declaration,
     whenever a function is declared static but never defined, whenever
     a label is declared but not used, and whenever a statement
     computes a result that is explicitly not used.

     To suppress this warning for an expression, simply cast it to
     void.  For unused variables and parameters, use the `unused'
     attribute.

`-Wuninitialized'
     An automatic variable is used without first being initialized.

     These warnings are possible only in optimizing compilation,
     because they require data flow information that is computed only
     when optimizing.  If you don't specify `-O', you simply won't get
     these warnings.

     These warnings occur only for variables that are candidates for
     register allocation.  Therefore, they do not occur for a variable
     that is declared `volatile', or whose address is taken, or whose
     size is other than 1, 2, 4 or 8 bytes.  Also, they do not occur for
     records or arrays, even when they are in registers.

     Note that there may be no warning about a variable that is used
     only to compute a value that itself is never used, because such
     computations may be deleted by data flow analysis before the
     warnings are printed.

     These warnings are made optional because GNU Pascal is not smart
     enough to see all the reasons why the code might be correct
     despite appearing to have an error.  Here is one example of how
     this can happen:

            Var
              x, y: Integer;
          
            ...
          
            case y of
              1: x:= 1;
              2: x:= 4;
              3: x:= 5;
            end (* case *);
            foo ( x );

     If the value of `y' is always 1, 2 or 3, then `x' is always
     initialized, but GNU Pascal doesn't know this.  Here is another
     common case:

            Var
              change_y: Boolean;
              y, new_y, save_y: Integer;
          
            ...
          
            if change_y then
              begin
                save_y:= y;
                y = new_y;
              end (* if *)
          
            ...
          
            if change_y then
              y:= save_y;

     This has no bug because `save_y' is used only if it is set.

     Some spurious warnings can be avoided if you declare all the
     functions you use that never return as `noreturn'.

`-Wall'
     All of the above `-W' options combined.  These are all the options
     which pertain to usage that we recommend avoiding and that we
     believe is easy to avoid, even in conjunction with macros.

   The remaining `-W...' options are not implied by `-Wall' because
they warn about constructions that we consider reasonable to use, on
occasion, in clean programs.

`-W'
     Print extra warning messages for these events:

        * A nonvolatile automatic variable might be changed by a call to
          `longjmp'.  These warnings as well are possible only in
          optimizing compilation.

          The compiler sees only the calls to `setjmp'.  It cannot know
          where `longjmp' will be called; in fact, a signal handler
          could call it at any point in the code.  As a result, you may
          get a warning even when there is in fact no problem because
          `longjmp' cannot in fact be called at the place which would
          cause a problem.

        * A function can return either with or without a value.
          (Falling off the end of the function body is considered
          returning without a value.)  For example, this function would
          evoke such a warning:

               foo (a)
               {
                 if (a > 0)
                   return a;
               }

        * An expression-statement or the left-hand side of a comma
          expression contains no side effects.  To suppress the
          warning, cast the unused expression to void.  For example, an
          expression such as `x[i,j]' will cause a warning, but
          `x[(void)i,j]' will not.

        * An unsigned value is compared against zero with `<' or `<='.

        * A comparison like `x<=y<=z' appears; this is equivalent to
          `(x<=y ? 1 : 0) <= z', which is a different interpretation
          from that of ordinary mathematical notation.

        * Storage-class specifiers like `static' are not the first
          things in a declaration.  According to the C Standard, this
          usage is obsolescent.

        * If `-Wall' or `-Wunused' is also specified, warn about unused
          arguments.

        * An aggregate has a partly bracketed initializer.  For
          example, the following code would evoke such a warning,
          because braces are missing around the initializer for `x.h':

               struct s { int f, g; };
               struct t { struct s h; int i; };
               struct t x = { 1, 2, 3 };

`-Wtraditional'
     Warn about certain constructs that behave differently in
     traditional and ANSI C.

        * Macro arguments occurring within string constants in the
          macro body.  These would substitute the argument in
          traditional C, but are part of the constant in ANSI C.

        * A function declared external in one block and then used after
          the end of the block.

        * A `switch' statement has an operand of type `long'.

`-Wshadow'
     Warn whenever a local variable shadows another local variable.

`-Wid-clash-LEN'
     Warn whenever two distinct identifiers match in the first LEN
     characters.  This may help you prepare a program that will compile
     with certain obsolete, brain-damaged compilers.

`-Wlarger-than-LEN'
     Warn whenever an object of larger than LEN bytes is defined.

`-Wpointer-arith'
     Warn about anything that depends on the "size of" a function type
     or of `void'.  GNU C assigns these types a size of 1, for
     convenience in calculations with `void *' pointers and pointers to
     functions.

`-Wbad-function-cast'
     Warn whenever a function call is cast to a non-matching type.  For
     example, warn if `int malloc()' is cast to `anything *'.

`-Wcast-qual'
     Warn whenever a pointer is cast so as to remove a type qualifier
     from the target type.  For example, warn if a `const char *' is
     cast to an ordinary `char *'.

`-Wcast-align'
     Warn whenever a pointer is cast such that the required alignment
     of the target is increased.  For example, warn if a `char *' is
     cast to an `int *' on machines where integers can only be accessed
     at two- or four-byte boundaries.

`-Wwrite-strings'
     Give string constants the type `const char[LENGTH]' so that
     copying the address of one into a non-`const' `char *' pointer
     will get a warning.  These warnings will help you find at compile
     time code that can try to write into a string constant, but only
     if you have been very careful about using `const' in declarations
     and prototypes.  Otherwise, it will just be a nuisance; this is
     why we did not make `-Wall' request these warnings.

`-Wconversion'
     Warn if a prototype causes a type conversion that is different
     from what would happen to the same argument in the absence of a
     prototype.  This includes conversions of fixed point to floating
     and vice versa, and conversions changing the width or signedness
     of a fixed point argument except when the same as the default
     promotion.

     Also, warn if a negative integer constant expression is implicitly
     converted to an unsigned type.  For example, warn about the
     assignment `x = -1' if `x' is unsigned.  But do not warn about
     explicit casts like `(unsigned) -1'.

`-Waggregate-return'
     Warn if any functions that return arrays or records are defined or
     called.

`-Wstrict-prototypes'
     Warn if a function is declared or defined without specifying the
     argument types.  (An old-style function definition is permitted
     without a warning if preceded by a declaration which specifies the
     argument types.)

`-Wmissing-prototypes'
     Warn if a global function is defined without a previous prototype
     declaration.  This warning is issued even if the definition itself
     provides a prototype.  The aim is to detect global functions that
     fail to be declared in header files.

`-Wmissing-declarations'
     Warn if a global function is defined without a previous
     declaration.  Do so even if the definition itself provides a
     prototype.  Use this option to detect global functions that are
     not declared in header files.

`-Wredundant-decls'
     Warn if anything is declared more than once in the same scope,
     even in cases where multiple declaration is valid and changes
     nothing.

`-Wnested-externs'
     Warn if an `extern' declaration is encountered within an function.

`-Winline'
     Warn if a function cannot be inlined, and either it was declared
     as inline, or else the `-finline-functions' option was given.

`-Woverloaded-virtual'
     Warn when a derived class function declaration may be an error in
     defining a virtual function (C++ only).  In a derived class, the
     definitions of virtual functions must match the type signature of a
     virtual function declared in the base class.  With this option, the
     compiler warns when you define a function with the same name as a
     virtual function, but with a type signature that does not match any
     declarations from the base class.

`-Wsynth (C++ only)'
     Warn when g++'s synthesis behavior does not match that of cfront.
     For instance:

          struct A {
            operator int ();
            A& operator = (int);
          };
          
          main ()
          {
            A a,b;
            a = b;
          }

     In this example, g++ will synthesize a default `A& operator =
     (const A&);', while cfront will use the user-defined `operator ='.

`-Werror'
     Make all warnings into errors.


File: gpc.info,  Node: Debugging Options,  Next: Optimize Options,  Prev: Warning Options,  Up: Invoking GPC

Options for Debugging Your Program or GNU Pascal
================================================

   GNU Pascal has various special options that are used for debugging
either your program or GPC:

`-g'
     Produce debugging information in the operating system's native
     format (stabs, COFF, XCOFF, or DWARF).  GDB can work with this
     debugging information.

     On most systems that use stabs format, `-g' enables use of extra
     debugging information that only GDB can use; this extra information
     makes debugging work better in GDB but will probably make other
     debuggers crash or refuse to read the program.  If you want to
     control for certain whether to generate the extra information, use
     `-gstabs+', `-gstabs', `-gxcoff+', `-gxcoff', `-gdwarf+', or
     `-gdwarf' (see below).

     Unlike most other C compilers, GNU Pascal allows you to use `-g'
     with `-O'.  The shortcuts taken by optimized code may occasionally
     produce surprising results: some variables you declared may not
     exist at all; flow of control may briefly move where you did not
     expect it; some statements may not be executed because they
     compute constant results or their values were already at hand;
     some statements may execute in different places because they were
     moved out of loops.

     Nevertheless it proves possible to debug optimized output.  This
     makes it reasonable to use the optimizer for programs that might
     have bugs.

     The following options are useful when GNU Pascal is generated with
     the capability for more than one debugging format.

`-ggdb'
     Produce debugging information in the native format (if that is
     supported), including GDB extensions if at all possible.

`-gstabs'
     Produce debugging information in stabs format (if that is
     supported), without GDB extensions.  This is the format used by
     DBX on most BSD systems.  On MIPS, Alpha and System V Release 4
     systems this option produces stabs debugging output which is not
     understood by DBX or SDB.  On System V Release 4 systems this
     option requires the GNU assembler.

`-gstabs+'
     Produce debugging information in stabs format (if that is
     supported), using GNU extensions understood only by the GNU
     debugger (GDB).  The use of these extensions is likely to make
     other debuggers crash or refuse to read the program.

`-gcoff'
     Produce debugging information in COFF format (if that is
     supported).  This is the format used by SDB on most System V
     systems prior to System V Release 4.

`-gxcoff'
     Produce debugging information in XCOFF format (if that is
     supported).  This is the format used by the DBX debugger on IBM
     RS/6000 systems.

`-gxcoff+'
     Produce debugging information in XCOFF format (if that is
     supported), using GNU extensions understood only by the GNU
     debugger (GDB).  The use of these extensions is likely to make
     other debuggers crash or refuse to read the program, and may cause
     assemblers other than the GNU assembler (GAS) to fail with an
     error.

`-gdwarf'
     Produce debugging information in DWARF format (if that is
     supported).  This is the format used by SDB on most System V
     Release 4 systems.

`-gdwarf+'
     Produce debugging information in DWARF format (if that is
     supported), using GNU extensions understood only by the GNU
     debugger (GDB).  The use of these extensions is likely to make
     other debuggers crash or refuse to read the program.

`-gLEVEL'
`-ggdbLEVEL'
`-gstabsLEVEL'
`-gcoffLEVEL'
`-gxcoffLEVEL'
`-gdwarfLEVEL'
     Request debugging information and also use LEVEL to specify how
     much information.  The default level is 2.

     Level 1 produces minimal information, enough for making backtraces
     in parts of the program that you don't plan to debug.  This
     includes descriptions of functions and external variables, but no
     information about local variables and no line numbers.

     Level 3 includes extra information, such as all the macro
     definitions present in the program.  Some debuggers support macro
     expansion when you use `-g3'.

`-p'
     Generate extra code to write profile information suitable for the
     analysis program `prof'.  You must use this option when compiling
     the source files you want data about, and you must also use it when
     linking.

`-pg'
     Generate extra code to write profile information suitable for the
     analysis program `gprof'.  You must use this option when compiling
     the source files you want data about, and you must also use it when
     linking.

`-a'
     Generate extra code to write profile information for basic blocks,
     which will record the number of times each basic block is
     executed, the basic block start address, and the function name
     containing the basic block.  If `-g' is used, the line number and
     filename of the start of the basic block will also be recorded.
     If not overridden by the machine description, the default action is
     to append to the text file `bb.out'.

     This data could be analyzed by a program like `tcov'.  Note,
     however, that the format of the data is not what `tcov' expects.
     Eventually GNU `gprof' should be extended to process this data.

`-dLETTERS'
     Says to make debugging dumps during compilation at times specified
     by LETTERS.  This is used for debugging the compiler.  The file
     names for most of the dumps are made by appending a word to the
     source file name (e.g. `foo.c.rtl' or `foo.c.jump').  Here are the
     possible letters for use in LETTERS, and their meanings:

    `M'
          Dump all macro definitions, at the end of preprocessing, and
          write no output.

    `N'
          Dump all macro names, at the end of preprocessing.

    `D'
          Dump all macro definitions, at the end of preprocessing, in
          addition to normal output.

    `Y'
          Dump source during parsing, to standard error.

    `y'
          Dump debugging information during parsing, to standard error.

    `r'
          Dump after RTL generation, to `FILE.rtl'.

    `x'
          Just generate RTL for a function instead of compiling it.
          Usually used with `r'.

    `j'
          Dump after first jump optimization, to `FILE.jump'.

    `s'
          Dump after CSE (including the jump optimization that sometimes
          follows CSE), to `FILE.cse'.

    `L'
          Dump after loop optimization, to `FILE.loop'.

    `t'
          Dump after the second CSE pass (including the jump
          optimization that sometimes follows CSE), to `FILE.cse2'.

    `f'
          Dump after flow analysis, to `FILE.flow'.

    `c'
          Dump after instruction combination, to the file
          `FILE.combine'.

    `S'
          Dump after the first instruction scheduling pass, to
          `FILE.sched'.

    `l'
          Dump after local register allocation, to `FILE.lreg'.

    `g'
          Dump after global register allocation, to `FILE.greg'.

    `R'
          Dump after the second instruction scheduling pass, to
          `FILE.sched2'.

    `J'
          Dump after last jump optimization, to `FILE.jump2'.

    `d'
          Dump after delayed branch scheduling, to `FILE.dbr'.

    `k'
          Dump after conversion from registers to stack, to
          `FILE.stack'.

    `a'
          Produce all the dumps listed above.

    `m'
          Print statistics on memory usage, at the end of the run, to
          standard error.

    `p'
          Annotate the assembler output with a comment indicating which
          pattern and alternative was used.

`-fdebug-gpi'
     Dump debugging information to stderr while reading or writing a
     GPI file.  *Note GPI files::

`-fpretend-float'
     When running a cross-compiler, pretend that the target machine
     uses the same floating point format as the host machine.  This
     causes incorrect output of the actual floating constants, but the
     actual instruction sequence will probably be the same as GNU
     Pascal would make when running on the target machine.

`-save-temps'
     Store the usual "temporary" intermediate files permanently; place
     them in the current directory and name them based on the source
     file.  Thus, compiling `foo.c' with `-c -save-temps' would produce
     files `foo.i' and `foo.s', as well as `foo.o'.

`-print-file-name=LIBRARY'
     Print the full absolute name of the library file LIBRARY that
     would be used when linking--and don't do anything else.  With this
     option, GNU Pascal does not compile or link anything; it just
     prints the file name.

`-print-prog-name=PROGRAM'
     Like `-print-file-name', but searches for a program such as `cpp'.

`-print-libgcc-file-name'
     Same as `-print-file-name=libgcc.a'.

     This is useful when you use `-nostdlib' or `-nodefaultlibs' but
     you do want to link with `libgcc.a'.  You can do

          gcc -nostdlib FILES... `gcc -print-libgcc-file-name`

`-print-search-dirs'
     Print the name of the configured installation directory and a list
     of program and library directories gcc will search--and don't do
     anything else.

     This is useful when gcc prints the error message `installation
     problem, cannot exec cpp: No such file or directory'.  To resolve
     this you either need to put `cpp' and the other compiler
     components where gcc expects to find them, or you can set the
     environment variable `GPC_EXEC_PREFIX' to the directory where you
     installed them.  Don't forget the trailing '/'.  *Note Environment
     Variables::.


File: gpc.info,  Node: Optimize Options,  Next: Preprocessor Options,  Prev: Debugging Options,  Up: Invoking GPC

Options That Control Optimization
=================================

   These options control various sorts of optimizations:

`-O'
`-O1'
     Optimize.  Optimizing compilation takes somewhat more time, and a
     lot more memory for a large function.

     Without `-O', the compiler's goal is to reduce the cost of
     compilation and to make debugging produce the expected results.
     Statements are independent: if you stop the program with a
     breakpoint between statements, you can then assign a new value to
     any variable or change the program counter to any other statement
     in the function and get exactly the results you would expect from
     the source code.

     With `-O', the compiler tries to reduce code size and execution
     time.

     When you specify `-O', the compiler turns on `-fthread-jumps' and
     `-fdefer-pop' on all machines.  The compiler turns on
     `-fdelayed-branch' on machines that have delay slots, and
     `-fomit-frame-pointer' on machines that can support debugging even
     without a frame pointer.  On some machines the compiler also turns
     on other flags.

`-O2'
     Optimize even more.  GNU Pascal performs nearly all supported
     optimizations that do not involve a space-speed tradeoff.  The
     compiler does not perform loop unrolling or function inlining when
     you specify `-O2'.  As compared to `-O', this option increases
     both compilation time and the performance of the generated code.

     `-O2' turns on all optional optimizations except for loop unrolling
     and function inlining.  It also turns on the `-fforce-mem' option
     on all machines and frame pointer elimination on machines where
     doing so does not interfere with debugging.

`-O3'
     Optimize yet more.  `-O3' turns on all optimizations specified by
     `-O2' and also turns on the `inline-functions' option.

`-O0'
     Do not optimize.

     If you use multiple `-O' options, with or without level numbers,
     the last such option is the one that is effective.

   Options of the form `-fFLAG' specify machine-independent flags.
Most flags have both positive and negative forms; the negative form of
`-ffoo' would be `-fno-foo'.  In the table below, only one of the forms
is listed--the one which is not the default.  You can figure out the
other form by either removing `no-' or adding it.

`-ffloat-store'
     Do not store floating point variables in registers, and inhibit
     other options that might change whether a floating point value is
     taken from a register or memory.

     This option prevents undesirable excess precision on machines such
     as the 68000 where the floating registers (of the 68881) keep more
     precision than a `double' is supposed to have.  For most programs,
     the excess precision does only good, but a few programs rely on the
     precise definition of IEEE floating point.  Use `-ffloat-store' for
     such programs.

`-fno-default-inline'
     Do not make member functions inline by default merely because they
     are defined inside the class scope (C++ only).  Otherwise, when
     you specify `-O', member functions defined inside class scope are
     compiled inline by default; i.e., you don't need to add `inline'
     in front of the member function name.

`-fno-defer-pop'
     Always pop the arguments to each function call as soon as that
     function returns.  For machines which must pop arguments after a
     function call, the compiler normally lets arguments accumulate on
     the stack for several function calls and pops them all at once.

`-fforce-mem'
     Force memory operands to be copied into registers before doing
     arithmetic on them.  This produces better code by making all memory
     references potential common subexpressions.  When they are not
     common subexpressions, instruction combination should eliminate
     the separate register-load.  The `-O2' option turns on this option.

`-fforce-addr'
     Force memory address constants to be copied into registers before
     doing arithmetic on them.  This may produce better code just as
     `-fforce-mem' may.

`-fomit-frame-pointer'
     Don't keep the frame pointer in a register for functions that
     don't need one.  This avoids the instructions to save, set up and
     restore frame pointers; it also makes an extra register available
     in many functions.  *It also makes debugging impossible on some
     machines.*

     On some machines, such as the Vax, this flag has no effect, because
     the standard calling sequence automatically handles the frame
     pointer and nothing is saved by pretending it doesn't exist.  The
     machine-description macro `FRAME_POINTER_REQUIRED' controls
     whether a target machine supports this flag.  *Note Registers:
     (gcc)Registers.

`-fno-inline'
     Don't pay attention to the `inline' keyword.  Normally this option
     is used to keep the compiler from expanding any functions inline.
     Note that if you are not optimizing, no functions can be expanded
     inline.

`-finline-functions'
     Integrate all simple functions into their callers.  The compiler
     heuristically decides which functions are simple enough to be worth
     integrating in this way.

     If all calls to a given function are integrated, and the function
     is declared `static', then the function is normally not output as
     assembler code in its own right.

`-fkeep-inline-functions'
     Even if all calls to a given function are integrated, and the
     function is declared `static', nevertheless output a separate
     run-time callable version of the function.

`-fno-function-cse'
     Do not put function addresses in registers; make each instruction
     that calls a constant function contain the function's address
     explicitly.

     This option results in less efficient code, but some strange hacks
     that alter the assembler output may be confused by the
     optimizations performed when this option is not used.

`-ffast-math'
     This option allows GPC to violate some ANSI or IEEE rules and/or
     specifications in the interest of optimizing code for speed.  For
     example, it allows the compiler to assume arguments to the `sqrt'
     function are non-negative numbers and that no floating-point values
     are NaNs.

     This option should never be turned on by any `-O' option since it
     can result in incorrect output for programs which depend on an
     exact implementation of IEEE or ANSI rules/specifications for math
     functions.

   The following options control specific optimizations.  The `-O2'
option turns on all of these optimizations except `-funroll-loops' and
`-funroll-all-loops'.  On most machines, the `-O' option turns on the
`-fthread-jumps' and `-fdelayed-branch' options, but specific machines
may handle it differently.

   You can use the following flags in the rare cases when "fine-tuning"
of optimizations to be performed is desired.

`-fstrength-reduce'
     Perform the optimizations of loop strength reduction and
     elimination of iteration variables.

`-fthread-jumps'
     Perform optimizations where we check to see if a jump branches to a
     location where another comparison subsumed by the first is found.
     If so, the first branch is redirected to either the destination of
     the second branch or a point immediately following it, depending
     on whether the condition is known to be true or false.

`-fcse-follow-jumps'
     In common subexpression elimination, scan through jump instructions
     when the target of the jump is not reached by any other path.  For
     example, when CSE encounters an `if' statement with an `else'
     clause, CSE will follow the jump when the condition tested is
     false.

`-fcse-skip-blocks'
     This is similar to `-fcse-follow-jumps', but causes CSE to follow
     jumps which conditionally skip over blocks.  When CSE encounters a
     simple `if' statement with no else clause, `-fcse-skip-blocks'
     causes CSE to follow the jump around the body of the `if'.

`-frerun-cse-after-loop'
     Re-run common subexpression elimination after loop optimizations
     has been performed.

`-fexpensive-optimizations'
     Perform a number of minor optimizations that are relatively
     expensive.

`-fdelayed-branch'
     If supported for the target machine, attempt to reorder
     instructions to exploit instruction slots available after delayed
     branch instructions.

`-fschedule-insns'
     If supported for the target machine, attempt to reorder
     instructions to eliminate execution stalls due to required data
     being unavailable.  This helps machines that have slow floating
     point or memory load instructions by allowing other instructions
     to be issued until the result of the load or floating point
     instruction is required.

`-fschedule-insns2'
     Similar to `-fschedule-insns', but requests an additional pass of
     instruction scheduling after register allocation has been done.
     This is especially useful on machines with a relatively small
     number of registers and where memory load instructions take more
     than one cycle.

`-fcaller-saves'
     Enable values to be allocated in registers that will be clobbered
     by function calls, by emitting extra instructions to save and
     restore the registers around such calls.  Such allocation is done
     only when it seems to result in better code than would otherwise
     be produced.

     This option is enabled by default on certain machines, usually
     those which have no call-preserved registers to use instead.

`-funroll-loops'
     Perform the optimization of loop unrolling.  This is only done for
     loops whose number of iterations can be determined at compile time
     or run time.  `-funroll-loop' implies both `-fstrength-reduce' and
     `-frerun-cse-after-loop'.

`-funroll-all-loops'
     Perform the optimization of loop unrolling.  This is done for all
     loops and usually makes programs run more slowly.
     `-funroll-all-loops' implies `-fstrength-reduce' as well as
     `-frerun-cse-after-loop'.

`-fno-peephole'
     Disable any machine-specific peephole optimizations.


File: gpc.info,  Node: Preprocessor Options,  Next: Assembler Options,  Prev: Optimize Options,  Up: Invoking GPC

Options Controlling the Preprocessor
====================================

   *Does the Pascal Preprocessor bring new options?*

   These options control the Pascal preprocessor, which is run on each
Pascal source file before actual compilation.

   If you use the `-E' option, nothing is done except preprocessing.
Some of these options make sense only together with `-E' because they
cause the preprocessor output to be unsuitable for actual compilation.

`-include FILE'
     Process FILE as input before processing the regular input file.
     In effect, the contents of FILE are compiled first.  Any `-D' and
     `-U' options on the command line are always processed before
     `-include FILE', regardless of the order in which they are
     written.  All the `-include' and `-imacros' options are processed
     in the order in which they are written.

`-imacros FILE'
     Process FILE as input, discarding the resulting output, before
     processing the regular input file.  Because the output generated
     from FILE is discarded, the only effect of `-imacros FILE' is to
     make the macros defined in FILE available for use in the main
     input.

     Any `-D' and `-U' options on the command line are always processed
     before `-imacros FILE', regardless of the order in which they are
     written.  All the `-include' and `-imacros' options are processed
     in the order in which they are written.

`-idirafter DIR'
     Add the directory DIR to the second include path.  The directories
     on the second include path are searched when a header file is not
     found in any of the directories in the main include path (the one
     that `-I' adds to).

`-iprefix PREFIX'
     Specify PREFIX as the prefix for subsequent `-iwithprefix' options.

`-iwithprefix DIR'
     Add a directory to the second include path.  The directory's name
     is made by concatenating PREFIX and DIR, where PREFIX was
     specified previously with `-iprefix'.  If you have not specified a
     prefix yet, the directory containing the installed passes of the
     compiler is used as the default.

`-iwithprefixbefore DIR'
     Add a directory to the main include path.  The directory's name is
     made by concatenating PREFIX and DIR, as in the case of
     `-iwithprefix'.

`-isystem DIR'
     Add a directory to the beginning of the second include path,
     marking it as a system directory, so that it gets the same special
     treatment as is applied to the standard system directories.

`-nostdinc'
     Do not search the standard system directories for header files.
     Only the directories you have specified with `-I' options (and the
     current directory, if appropriate) are searched.  *Note Directory
     Options::, for information on `-I'.

     By using both `-nostdinc' and `-I-', you can limit the include-file
     search path to only those directories you specify explicitly.

`-undef'
     Do not predefine any nonstandard macros.  (Including architecture
     flags).

`-E'
     Run only the Pascal preprocessor.  Preprocess all the Pascal
     source files specified and output the results to standard output
     or to the specified output file.

`-C'
     Tell the preprocessor not to discard comments.  Used with the `-E'
     option.

`-P'
     Tell the preprocessor not to generate `#line' directives.  Used
     with the `-E' option.

`-M'
     Tell the preprocessor to output a rule suitable for `make'
     describing the dependencies of each object file.  For each source
     file, the preprocessor outputs one `make'-rule whose target is the
     object file name for that source file and whose dependencies are
     all the `$include' header files it uses.  This rule may be a
     single line or may be continued with `\'-newline if it is long.
     The list of rules is printed on standard output instead of the
     preprocessed Pascal program.

     `-M' implies `-E'.

     Another way to specify output of a `make' rule is by setting the
     environment variable `DEPENDENCIES_OUTPUT' (*note Environment
     Variables::.).

`-MM'
     Like `-M' but the output mentions only the user header files
     included with `#include "FILE"'.  System header files included
     with `#include <FILE>' are omitted.

`-MD'
     Like `-M' but the dependency information is written to a file made
     by replacing ".c" with ".d" at the end of the input file names.
     This is in addition to compiling the file as specified--`-MD' does
     not inhibit ordinary compilation the way `-M' does.

     In Mach, you can use the utility `md' to merge multiple dependency
     files into a single dependency file suitable for using with the
     `make' command.

`-MMD'
     Like `-MD' except mention only user header files, not system
     header files.

`-MG'
     Treat missing header files as generated files and assume they live
     in the same directory as the source file.  If you specify `-MG',
     you must also specify either `-M' or `-MM'.  `-MG' is not
     supported with `-MD' or `-MMD'.

`-H'
     Print the name of each header file used, in addition to other
     normal activities.

`-AQUESTION(ANSWER)'
     Assert the answer ANSWER for QUESTION, in case it is tested with a
     preprocessing conditional such as `#if #QUESTION(ANSWER)'.  `-A-'
     disables the standard assertions that normally describe the target
     machine.

`-DMACRO'
     Define macro MACRO with the string `1' as its definition.

`-DMACRO=DEFN'
     Define macro MACRO as DEFN.  All instances of `-D' on the command
     line are processed before any `-U' options.

`-UMACRO'
     Undefine macro MACRO.  `-U' options are evaluated after all `-D'
     options, but before any `-include' and `-imacros' options.

`-dM'
     Tell the preprocessor to output only a list of the macro
     definitions that are in effect at the end of preprocessing.  Used
     with the `-E' option.

`-dD'
     Tell the preprocessing to pass all macro definitions into the
     output, in their proper sequence in the rest of the output.

`-dN'
     Like `-dD' except that the macro arguments and contents are
     omitted.  Only `#define NAME' is included in the output.

`-trigraphs'
     Support ANSI C trigraphs.  The `-ansi' option also has this effect.

`-Wp,OPTION'
     Pass OPTION as an option to the preprocessor.  If OPTION contains
     commas, it is split into multiple options at the commas.


File: gpc.info,  Node: Assembler Options,  Next: Link Options,  Prev: Preprocessor Options,  Up: Invoking GPC

Passing Options to the Assembler
================================

   You can pass options to the assembler.

`-Wa,OPTION'
     Pass OPTION as an option to the assembler.  If OPTION contains
     commas, it is split into multiple options at the commas.


File: gpc.info,  Node: Link Options,  Next: Directory Options,  Prev: Assembler Options,  Up: Invoking GPC

Options for Linking
===================

   These options come into play when the compiler links object files
into an executable output file.  They are meaningless if the compiler is
not doing a link step.

`OBJECT-FILE-NAME'
     A file name that does not end in a special recognized suffix is
     considered to name an object file or library.  (Object files are
     distinguished from libraries by the linker according to the file
     contents.)  If linking is done, these object files are used as
     input to the linker.

`-c'
`-S'
`-E'
     If any of these options is used, then the linker is not run, and
     object file names should not be used as arguments.  *Note Overall
     Options::.

`-lLIBRARY'
     Search the library named LIBRARY when linking.

     It makes a difference where in the command you write this option;
     the linker searches processes libraries and object files in the
     order they are specified.  Thus, `foo.o -lz bar.o' searches
     library `z' after file `foo.o' but before `bar.o'.  If `bar.o'
     refers to functions in `z', those functions may not be loaded.

     The linker searches a standard list of directories for the library,
     which is actually a file named `libLIBRARY.a'.  The linker then
     uses this file as if it had been specified precisely by name.

     The directories searched include several standard system
     directories plus any that you specify with `-L'.

     Normally the files found this way are library files--archive files
     whose members are object files.  The linker handles an archive
     file by scanning through it for members which define symbols that
     have so far been referenced but not defined.  But if the file that
     is found is an ordinary object file, it is linked in the usual
     fashion.  The only difference between using an `-l' option and
     specifying a file name is that `-l' surrounds LIBRARY with `lib'
     and `.a' and searches several directories.

`-lobjc'
     You need this special case of the `-l' option in order to link an
     Objective C program.

`-nostartfiles'
     Do not use the standard system startup files when linking.  The
     standard system libraries are used normally, unless `-nostdlib' or
     `-nodefaultlibs' is used.

`-nodefaultlibs'
     Do not use the standard system libraries when linking.  Only the
     libraries you specify will be passed to the linker.  The standard
     startup files are used normally, unless `-nostartfiles' is used.

`-nostdlib'
     Do not use the standard system startup files or libraries when
     linking.  No startup files and only the libraries you specify will
     be passed to the linker.

     One of the standard libraries bypassed by `-nostdlib' and
     `-nodefaultlibs' is `libgcc.a', a library of internal subroutines
     that GNU Pascal uses to overcome shortcomings of particular
     machines, or special needs for some languages.  In most cases, you
     need `libgcc.a' even when you want to avoid other standard
     libraries.  In other words, when you specify `-nostdlib' or
     `-nodefaultlibs' you should usually specify `-lgcc' as well.  This
     ensures that you have no unresolved references to internal GNU
     Pascal library subroutines.  (For example, `__main', used to
     ensure C++ constructors will be called;

`-s'
     Remove all symbol table and relocation information from the
     executable.

`-static'
     On systems that support dynamic linking, this prevents linking
     with the shared libraries.  On other systems, this option has no
     effect.

`-shared'
     Produce a shared object which can then be linked with other
     objects to form an executable.  Only a few systems support this
     option.

`-symbolic'
     Bind references to global symbols when building a shared object.
     Warn about any unresolved references (unless overridden by the
     link editor option `-Xlinker -z -Xlinker defs').  Only a few
     systems support this option.

`-Xlinker OPTION'
     Pass OPTION as an option to the linker.  You can use this to
     supply system-specific linker options which GNU Pascal does not
     know how to recognize.

     If you want to pass an option that takes an argument, you must use
     `-Xlinker' twice, once for the option and once for the argument.
     For example, to pass `-assert definitions', you must write
     `-Xlinker -assert -Xlinker definitions'.  It does not work to write
     `-Xlinker "-assert definitions"', because this passes the entire
     string as a single argument, which is not what the linker expects.

`-Wl,OPTION'
     Pass OPTION as an option to the linker.  If OPTION contains
     commas, it is split into multiple options at the commas.

`-u SYMBOL'
     Pretend the symbol SYMBOL is undefined, to force linking of
     library modules to define it.  You can use `-u' multiple times with
     different symbols to force loading of additional library modules.


File: gpc.info,  Node: Directory Options,  Next: Target Options,  Prev: Link Options,  Up: Invoking GPC

Options for Directory Search
============================

   These options specify directories to search for header files, for
libraries and for parts of the compiler:

`-IDIR'
     Add the directory DIRECTORY to the head of the list of directories
     to be searched for header files.  This can be used to override a
     system header file, substituting your own version, since these
     directories are searched before the system header file
     directories.  If you use more than one `-I' option, the
     directories are scanned in left-to-right order; the standard
     system directories come after.

`-I-'
     Any directories you specify with `-I' options before the `-I-'
     option are searched only for the case of `#include "FILE"'; they
     are not searched for `#include <FILE>'.

     If additional directories are specified with `-I' options after
     the `-I-', these directories are searched for all `#include'
     directives.  (Ordinarily *all* `-I' directories are used this way.)

     In addition, the `-I-' option inhibits the use of the current
     directory (where the current input file came from) as the first
     search directory for `#include "FILE"'.  There is no way to
     override this effect of `-I-'.  With `-I.' you can specify
     searching the directory which was current when the compiler was
     invoked.  That is not exactly the same as what the preprocessor
     does by default, but it is often satisfactory.

     `-I-' does not inhibit the use of the standard system directories
     for header files.  Thus, `-I-' and `-nostdinc' are independent.

`-LDIR'
     Add directory DIR to the list of directories to be searched for
     `-l'.

`-BPREFIX'
     This option specifies where to find the executables, libraries,
     include files, and data files of the compiler itself.

     The compiler driver program runs one or more of the subprograms
     `cpp', `cc1', `as' and `ld'.  It tries PREFIX as a prefix for each
     program it tries to run, both with and without `MACHINE/VERSION/'
     (*note Target Options::.).

     For each subprogram to be run, the compiler driver first tries the
     `-B' prefix, if any.  If that name is not found, or if `-B' was
     not specified, the driver tries two standard prefixes, which are
     `/usr/lib/gcc/' and `/usr/local/lib/gcc-lib/'.  If neither of
     those results in a file name that is found, the unmodified program
     name is searched for using the directories specified in your
     `PATH' environment variable.

     `-B' prefixes that effectively specify directory names also apply
     to libraries in the linker, because the compiler translates these
     options into `-L' options for the linker.  They also apply to
     includes files in the preprocessor, because the compiler
     translates these options into `-isystem' options for the
     preprocessor.  In this case, the compiler appends `include' to the
     prefix.

     The run-time support file `libgcc.a' can also be searched for using
     the `-B' prefix, if needed.  If it is not found there, the two
     standard prefixes above are tried, and that is all.  The file is
     left out of the link if it is not found by those means.

     Another way to specify a prefix much like the `-B' prefix is to use
     the environment variable `GPC_EXEC_PREFIX'.  *Note Environment
     Variables::.


File: gpc.info,  Node: Target Options,  Next: Submodel Options,  Prev: Directory Options,  Up: Invoking GPC

Specifying Target Machine and Compiler Version
==============================================

   By default, GNU Pascal compiles code for the same type of machine
that you are using.  However, it can also be installed as a
cross-compiler, to compile for some other type of machine.  In fact,
several different configurations of GNU Pascal, for different target
machines, can be installed side by side.  Then you specify which one to
use with the `-b' option.

   In addition, older and newer versions of GNU Pascal can be installed
side by side.  One of them (probably the newest) will be the default,
but you may sometimes wish to use another.

`-b MACHINE'
     The argument MACHINE specifies the target machine for compilation.
     This is useful when you have installed GNU Pascal as a
     cross-compiler.

     The value to use for MACHINE is the same as was specified as the
     machine type when configuring GNU Pascal as a cross-compiler.  For
     example, if a cross-compiler was configured with `configure
     i386v', meaning to compile for an 80386 running System V, then you
     would specify `-b i386v' to run that cross compiler.

     When you do not specify `-b', it normally means to compile for the
     same type of machine that you are using.

`-V VERSION'
     The argument VERSION specifies which version of GNU Pascal to run.
     This is useful when multiple versions are installed.  For example,
     VERSION might be `2.0', meaning to run GNU Pascal version 2.0.

     The default version, when you do not specify `-V', is the last
     version of GNU Pascal that you installed.

   The `-b' and `-V' options actually work by controlling part of the
file name used for the executable files and libraries used for
compilation.  A given version of GNU Pascal, for a given target
machine, is normally kept in the directory
`/usr/local/lib/gcc-lib/MACHINE/VERSION'.

   Thus, sites can customize the effect of `-b' or `-V' either by
changing the names of these directories or adding alternate names (or
symbolic links).  If in directory `/usr/local/lib/gcc-lib/' the file
`80386' is a link to the file `i386v', then `-b 80386' becomes an alias
for `-b i386v'.

   In one respect, the `-b' or `-V' do not completely change to a
different compiler: the top-level driver program `gpc' that you
originally invoked continues to run and invoke the other executables
(preprocessor, compiler per se, assembler and linker) that do the real
work.  However, since no real work is done in the driver program, it
usually does not matter that the driver program in use is not the one
for the specified target and version.

   The only way that the driver program depends on the target machine is
in the parsing and handling of special machine-specific options.
However, this is controlled by a file which is found, along with the
other executables, in the directory for the specified version and
target machine.  As a result, a single installed driver program adapts
to any specified target machine and compiler version.

   The driver program executable does control one significant thing,
however: the default version and target machine.  Therefore, you can
install different instances of the driver program, compiled for
different targets or versions, under different names.

   For example, if the driver for version 2.0 is installed as `ogcc'
and that for version 2.1 is installed as `gpc', then the command `gpc'
will use version 2.1 by default, while `ogcc' will use 2.0 by default.
However, you can choose either version with either command with the
`-V' option.


File: gpc.info,  Node: Submodel Options,  Next: Environment Variables,  Prev: Target Options,  Up: Invoking GPC

Hardware Models and Configurations
==================================

   Earlier we discussed the standard option `-b' which chooses among
different installed compilers for completely different target machines,
such as Vax vs. 68000 vs. 80386.

   In addition, each of these target machine types can have its own
special options, starting with `-m', to choose among various hardware
models or configurations--for example, 68010 vs 68020, floating
coprocessor or none.  A single installed version of the compiler can
compile for any model or configuration, according to the options
specified.

   Some configurations of the compiler also support additional special
options, usually for compatibility with other compilers on the same
platform.

   These options are defined by the macro `TARGET_SWITCHES' in the
machine description.  The default for the options is also defined by
that macro, which enables you to change the defaults.

* Menu:

* M680x0 Options::
* VAX Options::
* SPARC Options::
* Convex Options::
* AMD29K Options::
* ARM Options::
* M88K Options::
* RS/6000 and PowerPC Options::
* RT Options::
* MIPS Options::
* i386 Options::
* HPPA Options::
* Intel 960 Options::
* DEC Alpha Options::
* Clipper Options::
* H8/300 Options::
* System V Options::


File: gpc.info,  Node: M680x0 Options,  Next: VAX Options,  Up: Submodel Options

M680x0 Options
--------------

   These are the `-m' options defined for the 68000 series.  The default
values for these options depends on which style of 68000 was selected
when the compiler was configured; the defaults for the most common
choices are given below.

`-m68000'
`-mc68000'
     Generate output for a 68000.  This is the default when the
     compiler is configured for 68000-based systems.

`-m68020'
`-mc68020'
     Generate output for a 68020.  This is the default when the
     compiler is configured for 68020-based systems.

`-m68881'
     Generate output containing 68881 instructions for floating point.
     This is the default for most 68020 systems unless `-nfp' was
     specified when the compiler was configured.

`-m68030'
     Generate output for a 68030.  This is the default when the
     compiler is configured for 68030-based systems.

`-m68040'
     Generate output for a 68040.  This is the default when the
     compiler is configured for 68040-based systems.

     This option inhibits the use of 68881/68882 instructions that have
     to be emulated by software on the 68040.  If your 68040 does not
     have code to emulate those instructions, use `-m68040'.

`-m68020-40'
     Generate output for a 68040, without using any of the new
     instructions.  This results in code which can run relatively
     efficiently on either a 68020/68881 or a 68030 or a 68040.  The
     generated code does use the 68881 instructions that are emulated
     on the 68040.

`-mfpa'
     Generate output containing Sun FPA instructions for floating point.

`-msoft-float'
     Generate output containing library calls for floating point.
     *Warning:* the requisite libraries are not available for all m68k
     targets.  Normally the facilities of the machine's usual C
     compiler are used, but this can't be done directly in
     cross-compilation.  You must make your own arrangements to provide
     suitable library functions for cross-compilation.  The embedded
     targets `m68k-*-aout' and `m68k-*-coff' do provide software
     floating point support.

`-mshort'
     Consider type `int' to be 16 bits wide, like `short int'.

`-mnobitfield'
     Do not use the bit-field instructions.  The `-m68000' option
     implies `-mnobitfield'.

`-mbitfield'
     Do use the bit-field instructions.  The `-m68020' option implies
     `-mbitfield'.  This is the default if you use a configuration
     designed for a 68020.

`-mrtd'
     Use a different function-calling convention, in which functions
     that take a fixed number of arguments return with the `rtd'
     instruction, which pops their arguments while returning.  This
     saves one instruction in the caller since there is no need to pop
     the arguments there.

     This calling convention is incompatible with the one normally used
     on Unix, so you cannot use it if you need to call libraries
     compiled with the Unix compiler.

     Also, you must provide function prototypes for all functions that
     take variable numbers of arguments (including `printf'); otherwise
     incorrect code will be generated for calls to those functions.

     In addition, seriously incorrect code will result if you call a
     function with too many arguments.  (Normally, extra arguments are
     harmlessly ignored.)

     The `rtd' instruction is supported by the 68010 and 68020
     processors, but not by the 68000.


File: gpc.info,  Node: VAX Options,  Next: SPARC Options,  Prev: M680x0 Options,  Up: Submodel Options

VAX Options
-----------

   These `-m' options are defined for the Vax:

`-munix'
     Do not output certain jump instructions (`aobleq' and so on) that
     the Unix assembler for the Vax cannot handle across long ranges.

`-mgnu'
     Do output those jump instructions, on the assumption that you will
     assemble with the GNU assembler.

`-mg'
     Output code for g-format floating point numbers instead of
     d-format.


File: gpc.info,  Node: SPARC Options,  Next: Convex Options,  Prev: VAX Options,  Up: Submodel Options

SPARC Options
-------------

   These `-m' switches are supported on the SPARC:

`-mno-app-regs'
`-mapp-regs'
     Specify `-mapp-regs' to generate output using the global registers
     2 through 4, which the SPARC SVR4 ABI reserves for applications.
     This is the default.

     To be fully SVR4 ABI compliant at the cost of some performance
     loss, specify `-mno-app-regs'.  You should compile libraries and
     system software with this option.

`-mfpu'
`-mhard-float'
     Generate output containing floating point instructions.  This is
     the default.

`-mno-fpu'
`-msoft-float'
     Generate output containing library calls for floating point.
     *Warning:* the requisite libraries are not available for all SPARC
     targets.  Normally the facilities of the machine's usual C
     compiler are used, but this cannot be done directly in
     cross-compilation.  You must make your own arrangements to provide
     suitable library functions for cross-compilation.  The embedded
     targets `sparc-*-aout' and `sparclite-*-*' do provide software
     floating point support.

     `-msoft-float' changes the calling convention in the output file;
     therefore, it is only useful if you compile *all* of a program with
     this option.  In particular, you need to compile `libgcc.a', the
     library that comes with GNU Pascal, with `-msoft-float' in order
     for this to work.

`-mhard-quad-float'
     Generate output containing quad-word (long double) floating point
     instructions.

`-msoft-quad-float'
     Generate output containing library calls for quad-word (long
     double) floating point instructions.  The functions called are
     those specified in the SPARC ABI.  This is the default.

     As of this writing, there are no sparc implementations that have
     hardware support for the quad-word floating point instructions.
     They all invoke a trap handler for one of these instructions, and
     then the trap handler emulates the effect of the instruction.
     Because of the trap handler overhead, this is much slower than
     calling the ABI library routines.  Thus the `-msoft-quad-float'
     option is the default.

`-mno-epilogue'
`-mepilogue'
     With `-mepilogue' (the default), the compiler always emits code for
     function exit at the end of each function.  Any function exit in
     the middle of the function (such as a return statement in C) will
     generate a jump to the exit code at the end of the function.

     With `-mno-epilogue', the compiler tries to emit exit code inline
     at every function exit.

`-mno-flat'
`-mflat'
     With `-mflat', the compiler does not generate save/restore
     instructions and will use a "flat" or single register window
     calling convention.  This model uses %i7 as the frame pointer and
     is compatible with the normal register window model.  Code from
     either may be intermixed although debugger support is still
     incomplete.  The local registers and the input registers (0-5) are
     still treated as "call saved" registers and will be saved on the
     stack as necessary.

     With `-mno-flat' (the default), the compiler emits save/restore
     instructions (except for leaf functions) and is the normal mode of
     operation.

`-mno-unaligned-doubles'
`-munaligned-doubles'
     Assume that doubles have 8 byte alignment.  This is the default.

     With `-munaligned-doubles', GNU Pascal assumes that doubles have 8
     byte alignment only if they are contained in another type, or if
     they have an absolute address.  Otherwise, it assumes they have 4
     byte alignment.  Specifying this option avoids some rare
     compatibility problems with code generated by other compilers.  It
     is not the default because it results in a performance loss,
     especially for floating point code.

`-mv8'
`-msparclite'
     These two options select variations on the SPARC architecture.

     By default (unless specifically configured for the Fujitsu
     SPARClite), GPC generates code for the v7 variant of the SPARC
     architecture.

     `-mv8' will give you SPARC v8 code.  The only difference from v7
     code is that the compiler emits the integer multiply and integer
     divide instructions which exist in SPARC v8 but not in SPARC v7.

     `-msparclite' will give you SPARClite code.  This adds the integer
     multiply, integer divide step and scan (`ffs') instructions which
     exist in SPARClite but not in SPARC v7.

`-mcypress'
`-msupersparc'
     These two options select the processor for which the code is
     optimised.

     With `-mcypress' (the default), the compiler optimizes code for the
     Cypress CY7C602 chip, as used in the SparcStation/SparcServer 3xx
     series.  This is also appropriate for the older SparcStation 1, 2,
     IPX etc.

     With `-msupersparc' the compiler optimizes code for the SuperSparc
     cpu, as used in the SparcStation 10, 1000 and 2000 series. This
     flag also enables use of the full SPARC v8 instruction set.

   In a future version of GPC, these options will very likely be
renamed to `-mcpu=cypress' and `-mcpu=supersparc'.

   These `-m' switches are supported in addition to the above on SPARC
V9 processors:

`-mmedlow'
     Generate code for the Medium/Low code model: assume a 32 bit
     address space.  Programs are statically linked, PIC is not
     supported.  Pointers are still 64 bits.

     It is very likely that a future version of GPC will rename this
     option.

`-mmedany'
     Generate code for the Medium/Anywhere code model: assume a 32 bit
     text segment starting at offset 0, and a 32 bit data segment
     starting anywhere (determined at link time).  Programs are
     statically linked, PIC is not supported.  Pointers are still 64
     bits.

     It is very likely that a future version of GPC will rename this
     option.

`-mint64'
     Types long and int are 64 bits.

`-mlong32'
     Types long and int are 32 bits.

`-mlong64'
`-mint32'
     Type long is 64 bits, and type int is 32 bits.

`-mstack-bias'
`-mno-stack-bias'
     With `-mstack-bias', GNU Pascal assumes that the stack pointer, and
     frame pointer if present, are offset by -2047 which must be added
     back when making stack frame references.  Otherwise, assume no
     such offset is present.


File: gpc.info,  Node: Convex Options,  Next: AMD29K Options,  Prev: SPARC Options,  Up: Submodel Options

Convex Options
--------------

   These `-m' options are defined for Convex:

`-mc1'
     Generate output for C1.  The code will run on any Convex machine.
     The preprocessor symbol `__convex__c1__' is defined.

`-mc2'
     Generate output for C2.  Uses instructions not available on C1.
     Scheduling and other optimizations are chosen for max performance
     on C2.  The preprocessor symbol `__convex_c2__' is defined.

`-mc32'
     Generate output for C32xx.  Uses instructions not available on C1.
     Scheduling and other optimizations are chosen for max performance
     on C32.  The preprocessor symbol `__convex_c32__' is defined.

`-mc34'
     Generate output for C34xx.  Uses instructions not available on C1.
     Scheduling and other optimizations are chosen for max performance
     on C34.  The preprocessor symbol `__convex_c34__' is defined.

`-mc38'
     Generate output for C38xx.  Uses instructions not available on C1.
     Scheduling and other optimizations are chosen for max performance
     on C38.  The preprocessor symbol `__convex_c38__' is defined.

`-margcount'
     Generate code which puts an argument count in the word preceding
     each argument list.  This is compatible with regular CC, and a few
     programs may need the argument count word.  GDB and other
     source-level debuggers do not need it; this info is in the symbol
     table.

`-mnoargcount'
     Omit the argument count word.  This is the default.

`-mvolatile-cache'
     Allow volatile references to be cached.  This is the default.

`-mvolatile-nocache'
     Volatile references bypass the data cache, going all the way to
     memory.  This is only needed for multi-processor code that does
     not use standard synchronization instructions.  Making
     non-volatile references to volatile locations will not necessarily
     work.

`-mlong32'
     Type long is 32 bits, the same as type int.  This is the default.

`-mlong64'
     Type long is 64 bits, the same as type long long.  This option is
     useless, because no library support exists for it.


File: gpc.info,  Node: AMD29K Options,  Next: ARM Options,  Prev: Convex Options,  Up: Submodel Options

AMD29K Options
--------------

   These `-m' options are defined for the AMD Am29000:

`-mdw'
     Generate code that assumes the `DW' bit is set, i.e., that byte and
     halfword operations are directly supported by the hardware.  This
     is the default.

`-mndw'
     Generate code that assumes the `DW' bit is not set.

`-mbw'
     Generate code that assumes the system supports byte and halfword
     write operations.  This is the default.

`-mnbw'
     Generate code that assumes the systems does not support byte and
     halfword write operations.  `-mnbw' implies `-mndw'.

`-msmall'
     Use a small memory model that assumes that all function addresses
     are either within a single 256 KB segment or at an absolute
     address of less than 256k.  This allows the `call' instruction to
     be used instead of a `const', `consth', `calli' sequence.

`-mnormal'
     Use the normal memory model: Generate `call' instructions only when
     calling functions in the same file and `calli' instructions
     otherwise.  This works if each file occupies less than 256 KB but
     allows the entire executable to be larger than 256 KB.  This is
     the default.

`-mlarge'
     Always use `calli' instructions.  Specify this option if you expect
     a single file to compile into more than 256 KB of code.

`-m29050'
     Generate code for the Am29050.

`-m29000'
     Generate code for the Am29000.  This is the default.

`-mkernel-registers'
     Generate references to registers `gr64-gr95' instead of to
     registers `gr96-gr127'.  This option can be used when compiling
     kernel code that wants a set of global registers disjoint from
     that used by user-mode code.

     Note that when this option is used, register names in `-f' flags
     must use the normal, user-mode, names.

`-muser-registers'
     Use the normal set of global registers, `gr96-gr127'.  This is the
     default.

`-mstack-check'
`-mno-stack-check'
     Insert (or do not insert) a call to `__msp_check' after each stack
     adjustment.  This is often used for kernel code.

`-mstorem-bug'
`-mno-storem-bug'
     `-mstorem-bug' handles 29k processors which cannot handle the
     separation of a mtsrim insn and a storem instruction (most 29000
     chips to date, but not the 29050).

`-mno-reuse-arg-regs'
`-mreuse-arg-regs'
     `-mno-reuse-arg-regs' tells the compiler to only use incoming
     argument registers for copying out arguments.  This helps detect
     calling a function with fewer arguments than it was declared with.

`-msoft-float'
     Generate output containing library calls for floating point.
     *Warning:* the requisite libraries are not part of GNU Pascal.
     Normally the facilities of the machine's usual C compiler are
     used, but this can't be done directly in cross-compilation.  You
     must make your own arrangements to provide suitable library
     functions for cross-compilation.


File: gpc.info,  Node: ARM Options,  Next: M88K Options,  Prev: AMD29K Options,  Up: Submodel Options

ARM Options
-----------

   These `-m' options are defined for Advanced RISC Machines (ARM)
architectures:

`-m2'
`-m3'
     These options are identical.  Generate code for the ARM2 and ARM3
     processors.  This option is the default.  You should also use this
     option to generate code for ARM6 processors that are running with a
     26-bit program counter.

`-m6'
     Generate code for the ARM6 processor when running with a 32-bit
     program counter.

`-mapcs'
     Generate a stack frame that is compliant with the ARM Procedure
     Call Standard for all functions, even if this is not strictly
     necessary for correct execution of the code.

`-mbsd'
     This option only applies to RISC iX.  Emulate the native BSD-mode
     compiler.  This is the default if `-ansi' is not specified.

`-mxopen'
     This option only applies to RISC iX.  Emulate the native
     X/Open-mode compiler.

`-mno-symrename'
     This option only applies to RISC iX.  Do not run the assembler
     post-processor, `symrename', after code has been assembled.
     Normally it is necessary to modify some of the standard symbols in
     preparation for linking with the RISC iX C library; this option
     suppresses this pass.  The post-processor is never run when the
     compiler is built for cross-compilation.


File: gpc.info,  Node: M88K Options,  Next: RS/6000 and PowerPC Options,  Prev: ARM Options,  Up: Submodel Options

M88K Options
------------

   These `-m' options are defined for Motorola 88k architectures:

`-m88000'
     Generate code that works well on both the m88100 and the m88110.

`-m88100'
     Generate code that works best for the m88100, but that also runs
     on the m88110.

`-m88110'
     Generate code that works best for the m88110, and may not run on
     the m88100.

`-mbig-pic'
     Obsolete option to be removed from the next revision.  Use `-fPIC'.

`-midentify-revision'
     Include an `ident' directive in the assembler output recording the
     source file name, compiler name and version, timestamp, and
     compilation flags used.

`-mno-underscores'
     In assembler output, emit symbol names without adding an underscore
     character at the beginning of each name.  The default is to use an
     underscore as prefix on each name.

`-mocs-debug-info'
`-mno-ocs-debug-info'
     Include (or omit) additional debugging information (about
     registers used in each stack frame) as specified in the 88open
     Object Compatibility Standard, "OCS".  This extra information
     allows debugging of code that has had the frame pointer
     eliminated.  The default for DG/UX, SVr4, and Delta 88 SVr3.2 is
     to include this information; other 88k configurations omit this
     information by default.

`-mocs-frame-position'
     When emitting COFF debugging information for automatic variables
     and parameters stored on the stack, use the offset from the
     canonical frame address, which is the stack pointer (register 31)
     on entry to the function.  The DG/UX, SVr4, Delta88 SVr3.2, and
     BCS configurations use `-mocs-frame-position'; other 88k
     configurations have the default `-mno-ocs-frame-position'.

`-mno-ocs-frame-position'
     When emitting COFF debugging information for automatic variables
     and parameters stored on the stack, use the offset from the frame
     pointer register (register 30).  When this option is in effect,
     the frame pointer is not eliminated when debugging information is
     selected by the -g switch.

`-moptimize-arg-area'
`-mno-optimize-arg-area'
     Control how function arguments are stored in stack frames.
     `-moptimize-arg-area' saves space by optimizing them, but this
     conflicts with the 88open specifications.  The opposite
     alternative, `-mno-optimize-arg-area', agrees with 88open
     standards.  By default GNU Pascal does not optimize the argument
     area.

`-mshort-data-NUM'
     Generate smaller data references by making them relative to `r0',
     which allows loading a value using a single instruction (rather
     than the usual two).  You control which data references are
     affected by specifying NUM with this option.  For example, if you
     specify `-mshort-data-512', then the data references affected are
     those involving displacements of less than 512 bytes.
     `-mshort-data-NUM' is not effective for NUM greater than 64k.

`-mserialize-volatile'
`-mno-serialize-volatile'
     Do, or don't, generate code to guarantee sequential consistency of
     volatile memory references.  By default, consistency is guaranteed.

     The order of memory references made by the MC88110 processor does
     not always match the order of the instructions requesting those
     references.  In particular, a load instruction may execute before
     a preceding store instruction.  Such reordering violates
     sequential consistency of volatile memory references, when there
     are multiple processors.   When consistency must be guaranteed,
     GNU Pascal generates special instructions, as needed, to force
     execution in the proper order.

     The MC88100 processor does not reorder memory references and so
     always provides sequential consistency.  However, by default, GNU
     C generates the special instructions to guarantee consistency even
     when you use `-m88100', so that the code may be run on an MC88110
     processor.  If you intend to run your code only on the MC88100
     processor, you may use `-mno-serialize-volatile'.

     The extra code generated to guarantee consistency may affect the
     performance of your application.  If you know that you can safely
     forgo this guarantee, you may use `-mno-serialize-volatile'.

`-msvr4'
`-msvr3'
     Turn on (`-msvr4') or off (`-msvr3') compiler extensions related
     to System V release 4 (SVr4).  This controls the following:

       1. Which variant of the assembler syntax to emit.

       2. `-msvr4' makes the Pascal preprocessor recognize `#pragma
          weak' that is used on System V release 4.

       3. `-msvr4' makes GNU Pascal issue additional declaration
          directives used in SVr4.

     `-msvr4' is the default for the m88k-motorola-sysv4 and
     m88k-dg-dgux m88k configurations. `-msvr3' is the default for all
     other m88k configurations.

`-mversion-03.00'
     This option is obsolete, and is ignored.

`-mno-check-zero-division'
`-mcheck-zero-division'
     Do, or don't, generate code to guarantee that integer division by
     zero will be detected.  By default, detection is guaranteed.

     Some models of the MC88100 processor fail to trap upon integer
     division by zero under certain conditions.  By default, when
     compiling code that might be run on such a processor, GNU C
     generates code that explicitly checks for zero-valued divisors and
     traps with exception number 503 when one is detected.  Use of
     mno-check-zero-division suppresses such checking for code
     generated to run on an MC88100 processor.

     GNU Pascal assumes that the MC88110 processor correctly detects all
     instances of integer division by zero.  When `-m88110' is
     specified, both `-mcheck-zero-division' and
     `-mno-check-zero-division' are ignored, and no explicit checks for
     zero-valued divisors are generated.

`-muse-div-instruction'
     Use the div instruction for signed integer division on the MC88100
     processor.  By default, the div instruction is not used.

     On the MC88100 processor the signed integer division instruction
     div) traps to the operating system on a negative operand.  The
     operating system transparently completes the operation, but at a
     large cost in execution time.  By default, when compiling code
     that might be run on an MC88100 processor, GNU Pascal emulates
     signed integer division using the unsigned integer division
     instruction divu), thereby avoiding the large penalty of a trap to
     the operating system.  Such emulation has its own, smaller,
     execution cost in both time and space.  To the extent that your
     code's important signed integer division operations are performed
     on two nonnegative operands, it may be desirable to use the div
     instruction directly.

     On the MC88110 processor the div instruction (also known as the
     divs instruction) processes negative operands without trapping to
     the operating system.  When `-m88110' is specified,
     `-muse-div-instruction' is ignored, and the div instruction is used
     for signed integer division.

     Note that the result of dividing INT_MIN by -1 is undefined.  In
     particular, the behavior of such a division with and without
     `-muse-div-instruction'  may differ.

`-mtrap-large-shift'
`-mhandle-large-shift'
     Include code to detect bit-shifts of more than 31 bits;
     respectively, trap such shifts or emit code to handle them
     properly.  By default GNU Pascal makes no special provision for
     large bit shifts.

`-mwarn-passed-structs'
     Warn when a function passes a struct as an argument or result.
     Structure-passing conventions have changed during the evolution of
     the C language, and are often the source of portability problems.
     By default, GNU Pascal issues no such warning.


File: gpc.info,  Node: RS/6000 and PowerPC Options,  Next: RT Options,  Prev: M88K Options,  Up: Submodel Options

IBM RS/6000 and PowerPC Options
-------------------------------

   These `-m' options are defined for the IBM RS/6000 and PowerPC:
`-mpower'
`-mno-power'
`-mpower2'
`-mno-power2'
`-mpowerpc'
`-mno-powerpc'
`-mpowerpc-gpopt'
`-mno-powerpc-gpopt'
`-mpowerpc-gfxopt'
`-mno-powerpc-gfxopt'
     GNU Pascal supports two related instruction set architectures for
     the RS/6000 and PowerPC.  The "POWER" instruction set are those
     instructions supported by the `rios' chip set used in the original
     RS/6000 systems and the "PowerPC" instruction set is the
     architecture of the Motorola MPC6xx microprocessors.  The PowerPC
     architecture defines 64-bit instructions, but they are not
     supported by any current processors.

     Neither architecture is a subset of the other.  However there is a
     large common subset of instructions supported by both.  An MQ
     register is included in processors supporting the POWER
     architecture.

     You use these options to specify which instructions are available
     on the processor you are using.  The default value of these
     options is determined when configuring GNU Pascal.  Specifying the
     `-mcpu=CPU_TYPE' overrides the specification of these options.  We
     recommend you use that option rather than these.

     The `-mpower' option allows GNU Pascal to generate instructions
     that are found only in the POWER architecture and to use the MQ
     register.  Specifying `-mpower2' implies `-power' and also allows
     GNU Pascal to generate instructions that are present in the POWER2
     architecture but not the original POWER architecture.

     The `-mpowerpc' option allows GNU Pascal to generate instructions
     that are found only in the 32-bit subset of the PowerPC
     architecture.  Specifying `-mpowerpc-gpopt' implies `-mpowerpc'
     and also allows GNU Pascal to use the optional PowerPC
     architecture instructions in the General Purpose group, including
     floating-point square root.  Specifying `-mpowerpc-gfxopt' implies
     `-mpowerpc' and also allows GNU Pascal to use the optional PowerPC
     architecture instructions in the Graphics group, including
     floating-point select.

     If you specify both `-mno-power' and `-mno-powerpc', GNU Pascal
     will use only the instructions in the common subset of both
     architectures plus some special AIX common-mode calls, and will
     not use the MQ register.  Specifying both `-mpower' and `-mpowerpc'
     permits GNU Pascal to use any instruction from either architecture
     and to allow use of the MQ register; specify this for the Motorola
     MPC601.

`-mnew-mnemonics'
`-mold-mnemonics'
     Select which mnemonics to use in the generated assembler code.
     `-mnew-mnemonics' requests output that uses the assembler mnemonics
     defined for the PowerPC architecture, while `-mold-mnemonics'
     requests the assembler mnemonics defined for the POWER
     architecture.  Instructions defined in only one architecture have
     only one mnemonic; GNU Pascal uses that mnemonic irrespective of
     which of these options is specified.

     PowerPC assemblers support both the old and new mnemonics, as will
     later POWER assemblers.  Current POWER assemblers only support the
     old mnemonics.  Specify `-mnew-mnemonics' if you have an assembler
     that supports them, otherwise specify `-mold-mnemonics'.

     The default value of these options depends on how GNU Pascal was
     configured.  Specifying `-mcpu=CPU_TYPE' sometimes overrides the
     value of these option.  Unless you are building a cross-compiler,
     you should normally not specify either `-mnew-mnemonics' or
     `-mold-mnemonics', but should instead accept the default.

`-mcpu=CPU_TYPE'
     Set architecture type, register usage, choice of mnemonics, and
     instruction scheduling parameters for machine type CPU_TYPE.  By
     default, CPU_TYPE is the target system defined when GNU Pascal was
     configured.  Supported values for CPU_TYPE are `rios1', `rios2',
     `rsc', `601', `603', `604', `power', `powerpc', `403', and
     `common'.  `-mcpu=power' and `-mcpu=powerpc' specify generic POWER
     and pure PowerPC (i.e., not MPC601) architecture machine types,
     with an appropriate, generic processor model assumed for
     scheduling purposes.

     Specifying `-mcpu=rios1', `-mcpu=rios2', `-mcpu=rsc', or
     `-mcpu=power' enables the `-mpower' option and disables the
     `-mpowerpc' option; `-mcpu=601' enables both the `-mpower' and
     `-mpowerpc' options; `-mcpu=603', `-mcpu=604', `-mcpu=403', and
     `-mcpu=powerpc' enable the `-mpowerpc' option and disable the
     `-mpower' option; `-mcpu=common' disables both the `-mpower' and
     `-mpowerpc' options.

     To generate code that will operate on all members of the RS/6000
     and PowerPC families, specify `-mcpu=common'.  In that case, GNU
     Pascal will use only the instructions in the common subset of both
     architectures plus some special AIX common-mode calls, and will
     not use the MQ register.  GNU Pascal assumes a generic processor
     model for scheduling purposes.

     Specifying `-mcpu=rios1', `-mcpu=rios2', `-mcpu=rsc', or
     `-mcpu=power' also disables the `new-mnemonics' option.
     Specifying `-mcpu=601', `-mcpu=603', `-mcpu=604', `403', or
     `-mcpu=powerpc' also enables the `new-mnemonics' option.

`-mfull-toc'
`-mno-fp-in-toc'
`-mno-sum-in-toc'
`-mminimal-toc'
     Modify generation of the TOC (Table Of Contents), which is created
     for every executable file.  The `-mfull-toc' option is selected by
     default.  In that case, GNU Pascal will allocate at least one TOC
     entry for each unique non-automatic variable reference in your
     program.  GNU Pascal will also place floating-point constants in
     the TOC.  However, only 16,384 entries are available in the TOC.

     If you receive a linker error message that saying you have
     overflowed the available TOC space, you can reduce the amount of
     TOC space used with the `-mno-fp-in-toc' and `-mno-sum-in-toc'
     options.  `-mno-fp-in-toc' prevents GNU Pascal from putting
     floating-point constants in the TOC and `-mno-sum-in-toc' forces
     GNU Pascal to generate code to calculate the sum of an address and
     a constant at run-time instead of putting that sum into the TOC.
     You may specify one or both of these options.  Each causes GNU
     Pascal to produce very slightly slower and larger code at the
     expense of conserving TOC space.

     If you still run out of space in the TOC even when you specify
     both of these options, specify `-mminimal-toc' instead.  This
     option causes GNU Pascal to make only one TOC entry for every
     file.  When you specify this option, GNU Pascal will produce code
     that is slower and larger but which uses extremely little TOC
     space.  You may wish to use this option only on files that contain
     less frequently executed code.

`-msoft-float'
`-mhard-float'
     Generate code that does not use (uses) the floating-point register
     set.  Software floating point emulation is provided if you use the
     `-msoft-float' option, and pass the option to GNU Pascal when
     linking.

`-mmultiple'
`-mno-multiple'
     Generate code that uses (does not use) the load multiple word
     instructions and the store multiple word instructions.  These
     instructions are generated by default on POWER systems, and not
     generated on PowerPC systems.  Do not use `-mmultiple' on little
     endian PowerPC systems, since those instructions do not work when
     the processor is in little endian mode.

`-mstring'
`-mno-string'
     Generate code that uses (does not use) the load string
     instructions and the store string word instructions to save
     multiple registers and do small block moves.  These instructions
     are generated by default on POWER systems, anod not generated on
     PowerPC systems.  Do not use `-mstring' on little endian PowerPC
     systems, since those instructions do not work when the processor
     is in little endian mode.

`-mno-bit-align'
`-mbit-align'
     On System V.4 and embedded PowerPC systems do not (do) force packed
     records to be aligned to the base type of the packed fields.

     For example, by default a record containing nothing but 8 Boolean
     fields would be aligned to a 4 byte boundary and have a size of 4
     bytes.  By using `-mno-bit-align', the record would be aligned to
     a 1 byte boundary and be one byte in size ... well--if `packed'
     would already work!

`-mno-strict-align'
`-mstrict-align'
     On System V.4 and embedded PowerPC systems do not (do) assume that
     unaligned memory references will be handled by the system.

`-mrelocatable'
`-mno-relocatable'
     On embedded PowerPC systems generate code that allows (does not
     allow) the program to be relocated to a different address at
     runtime.

`-mno-toc'
`-mtoc'
     On System V.4 and embedded PowerPC systems do not (do) assume that
     register 2 contains a pointer to a global area pointing to the
     addresses used in the program.

`-mno-traceback'
`-mtraceback'
     On embedded PowerPC systems do not (do) generate a traceback tag
     before the start of the function.  This tag can be used by the
     debugger to identify where the start of a function is.

`-mlittle'
`-mlittle-endian'
     On System V.4 and embedded PowerPC systems compile code for the
     processor in little endian mode.  The `-mlittle-endian' option is
     the same as `-mlittle'.

`-mbig'
`-mbig-endian'
     On System V.4 and embedded PowerPC systems compile code for the
     processor in big endian mode.  The `-mbig-endian' option is the
     same as `-mbig'.

`-mcall-sysv'
     On System V.4 and embedded PowerPC systems compile code using
     calling conventions that adheres to the March 1995 draft of the
     System V Application Binary Interface, PowerPC processor
     supplement.  This is the default unless you configured GPC using
     `powerpc-*-eabiaix'.

`-mcall-aix'
     On System V.4 and embedded PowerPC systems compile code using
     calling conventions that are similar to those used on AIX.  This
     is the default if you configured GPC using `powerpc-*-eabiaix'.

`-mprototype'
`-mno-prototype'
     On System V.4 and embedded PowerPC systems assume that all calls to
     variable argument functions are properly prototyped.  Otherwise,
     the compiler must insert an instruction before every non
     prototyped call to set or clear bit 6 of the condition code
     register (CR) to indicate whether floating point values were
     passed in the floating point registers in case the function takes
     a variable arguments.  With `-mprototype', only calls to
     prototyped variable argument functions will set or clear the bit.


File: gpc.info,  Node: RT Options,  Next: MIPS Options,  Prev: RS/6000 and PowerPC Options,  Up: Submodel Options

IBM RT Options
--------------

   These `-m' options are defined for the IBM RT PC:

`-min-line-mul'
     Use an in-line code sequence for integer multiplies.  This is the
     default.

`-mcall-lib-mul'
     Call `lmul$$' for integer multiples.

`-mfull-fp-blocks'
     Generate full-size floating point data blocks, including the
     minimum amount of scratch space recommended by IBM.  This is the
     default.

`-mminimum-fp-blocks'
     Do not include extra scratch space in floating point data blocks.
     This results in smaller code, but slower execution, since scratch
     space must be allocated dynamically.

`-mfp-arg-in-fpregs'
     Use a calling sequence incompatible with the IBM calling
     convention in which floating point arguments are passed in
     floating point registers.  Note that `varargs.h' and `stdargs.h'
     will not work with floating point operands if this option is
     specified.

`-mfp-arg-in-gregs'
     Use the normal calling convention for floating point arguments.
     This is the default.

`-mhc-struct-return'
     Return structures of more than one word in memory, rather than in a
     register.  This provides compatibility with the MetaWare HighC (hc)
     compiler.  Use the option `-fpcc-struct-return' for compatibility
     with the Portable C Compiler (pcc).

`-mnohc-struct-return'
     Return some structures of more than one word in registers, when
     convenient.  This is the default.  For compatibility with the
     IBM-supplied compilers, use the option `-fpcc-struct-return' or the
     option `-mhc-struct-return'.


File: gpc.info,  Node: MIPS Options,  Next: i386 Options,  Prev: RT Options,  Up: Submodel Options

MIPS Options
------------

   These `-m' options are defined for the MIPS family of computers:

`-mcpu=CPU TYPE'
     Assume the defaults for the machine type CPU TYPE when scheduling
     instructions.  The choices for CPU TYPE are `r2000', `r3000',
     `r4000', `r4400', `r4600', and `r6000'.  While picking a specific
     CPU TYPE will schedule things appropriately for that particular
     chip, the compiler will not generate any code that does not meet
     level 1 of the MIPS ISA (instruction set architecture) without the
     `-mips2' or `-mips3' switches being used.

`-mips1'
     Issue instructions from level 1 of the MIPS ISA.  This is the
     default.  `r3000' is the default CPU TYPE at this ISA level.

`-mips2'
     Issue instructions from level 2 of the MIPS ISA (branch likely,
     square root instructions).  `r6000' is the default CPU TYPE at this
     ISA level.

`-mips3'
     Issue instructions from level 3 of the MIPS ISA (64 bit
     instructions).  `r4000' is the default CPU TYPE at this ISA level.
     This option does not change the sizes of any of the Pascal data
     types.

`-mfp32'
     Assume that 32 32-bit floating point registers are available.
     This is the default.

`-mfp64'
     Assume that 32 64-bit floating point registers are available.
     This is the default when the `-mips3' option is used.

`-mgp32'
     Assume that 32 32-bit general purpose registers are available.
     This is the default.

`-mgp64'
     Assume that 32 64-bit general purpose registers are available.
     This is the default when the `-mips3' option is used.

`-mint64'
     Types long, int, and pointer are 64 bits.  This works only if
     `-mips3' is also specified.

`-mlong64'
     Types long and pointer are 64 bits, and type int is 32 bits.  This
     works only if `-mips3' is also specified.

`-mmips-as'
     Generate code for the MIPS assembler, and invoke `mips-tfile' to
     add normal debug information.  This is the default for all
     platforms except for the OSF/1 reference platform, using the
     OSF/rose object format.  If the either of the `-gstabs' or
     `-gstabs+' switches are used, the `mips-tfile' program will
     encapsulate the stabs within MIPS ECOFF.

`-mgas'
     Generate code for the GNU assembler.  This is the default on the
     OSF/1 reference platform, using the OSF/rose object format.

`-mrnames'
`-mno-rnames'
     The `-mrnames' switch says to output code using the MIPS software
     names for the registers, instead of the hardware names (ie, A0
     instead of $4).  The only known assembler that supports this option
     is the Algorithmics assembler.

`-mgpopt'
`-mno-gpopt'
     The `-mgpopt' switch says to write all of the data declarations
     before the instructions in the text section, this allows the MIPS
     assembler to generate one word memory references instead of using
     two words for short global or static data items.  This is on by
     default if optimization is selected.

`-mstats'
`-mno-stats'
     For each non-inline function processed, the `-mstats' switch
     causes the compiler to emit one line to the standard error file to
     print statistics about the program (number of registers saved,
     stack size, etc.).

`-mmemcpy'
`-mno-memcpy'
     The `-mmemcpy' switch makes all block moves call the appropriate
     string function (`memcpy' or `bcopy') instead of possibly
     generating inline code.

`-mmips-tfile'
`-mno-mips-tfile'
     The `-mno-mips-tfile' switch causes the compiler not postprocess
     the object file with the `mips-tfile' program, after the MIPS
     assembler has generated it to add debug support.  If `mips-tfile'
     is not run, then no local variables will be available to the
     debugger.  In addition, `stage2' and `stage3' objects will have
     the temporary file names passed to the assembler embedded in the
     object file, which means the objects will not compare the same.
     The `-mno-mips-tfile' switch should only be used when there are
     bugs in the `mips-tfile' program that prevents compilation.

`-msoft-float'
     Generate output containing library calls for floating point.
     *Warning:* the requisite libraries are not part of GNU Pascal.
     Normally the facilities of the machine's usual C compiler are
     used, but this can't be done directly in cross-compilation.  You
     must make your own arrangements to provide suitable library
     functions for cross-compilation.

`-mhard-float'
     Generate output containing floating point instructions.  This is
     the default if you use the unmodified sources.

`-mabicalls'
`-mno-abicalls'
     Emit (or do not emit) the pseudo operations `.abicalls',
     `.cpload', and `.cprestore' that some System V.4 ports use for
     position independent code.

`-mlong-calls'
`-mno-long-calls'
     Do all calls with the `JALR' instruction, which requires loading
     up a function's address into a register before the call.  You need
     to use this switch, if you call outside of the current 512
     megabyte segment to functions that are not through pointers.

`-mhalf-pic'
`-mno-half-pic'
     Put pointers to extern references into the data section and load
     them up, rather than put the references in the text section.

`-membedded-pic'
`-mno-embedded-pic'
     Generate PIC code suitable for some embedded systems.  All calls
     are made using PC relative address, and all data is addressed
     using the $gp register.  This requires GNU as and GNU ld which do
     most of the work.

`-membedded-data'
`-mno-embedded-data'
     Allocate variables to the read-only data section first if
     possible, then next in the small data section if possible,
     otherwise in data.  This gives slightly slower code than the
     default, but reduces the amount of RAM required when executing,
     and thus may be preferred for some embedded systems.

`-msingle-float'
`-mdouble-float'
     The `-msingle-float' switch tells gcc to assume that the floating
     point coprocessor only supports single precision operations, as on
     the `r4650' chip.  The `-mdouble-float' switch permits gcc to use
     double precision operations.  This is the default.

`-mmad'
`-mno-mad'
     Permit use of the `mad', `madu' and `mul' instructions, as on the
     `r4650' chip.

`-m4650'
     Turns on `-msingle-float', `-mmad', and, at least for now,
     `-mcpu=r4650'.

`-EL'
     Compile code for the processor in little endian mode.  The
     requisite libraries are assumed to exist.

`-EB'
     Compile code for the processor in big endian mode.  The requisite
     libraries are assumed to exist.

`-G NUM'
     Put global and static items less than or equal to NUM bytes into
     the small data or bss sections instead of the normal data or bss
     section.  This allows the assembler to emit one word memory
     reference instructions based on the global pointer (GP or $28),
     instead of the normal two words used.  By default, NUM is 8 when
     the MIPS assembler is used, and 0 when the GNU assembler is used.
     The `-G NUM' switch is also passed to the assembler and linker.
     All modules should be compiled with the same `-G NUM' value.

`-nocpp'
     Tell the MIPS assembler to not run it's preprocessor over user
     assembler files (with a `.s' suffix) when assembling them.

   These options are defined by the macro `TARGET_SWITCHES' in the
machine description.  The default for the options is also defined by
that macro, which enables you to change the defaults.


File: gpc.info,  Node: i386 Options,  Next: HPPA Options,  Prev: MIPS Options,  Up: Submodel Options

Intel 386 Options
-----------------

   These `-m' options are defined for the i386 family of computers:

`-m486'
`-m386'
     Control whether or not code is optimized for a 486 instead of an
     386.  Code generated for an 486 will run on a 386 and vice versa.

`-mieee-fp'
`-mno-ieee-fp'
     Control whether or not the compiler uses IEEE floating point
     comparisons.  These handle correctly the case where the result of a
     comparison is unordered.

`-msoft-float'
     Generate output containing library calls for floating point.
     *Warning:* the requisite libraries are not part of GNU Pascal.
     Normally the facilities of the machine's usual C compiler are
     used, but this can't be done directly in cross-compilation.  You
     must make your own arrangements to provide suitable library
     functions for cross-compilation.

     On machines where a function returns floating point results in the
     80387 register stack, some floating point opcodes may be emitted
     even if `-msoft-float' is used.

`-mno-fp-ret-in-387'
     Do not use the FPU registers for return values of functions.

     The usual calling convention has functions return values of types
     `float' and `double' in an FPU register, even if there is no FPU.
     The idea is that the operating system should emulate an FPU.

     The option `-mno-fp-ret-in-387' causes such values to be returned
     in ordinary CPU registers instead.

`-mno-fancy-math-387'
     Some 387 emulators do not support the `sin', `cos' and `sqrt'
     instructions for the 387.  Specify this option to avoid generating
     those instructions. This option is the default on FreeBSD.  As of
     revision 2.6.1, these instructions are not generated unless you
     also use the `-ffast-math' switch.

`-malign-double'
`-mno-align-double'
     Control whether GNU Pascal aligns `double', `long double', and
     `long long' variables on a two word boundary or a one word
     boundary.  Aligning `double' variables on a two word boundary will
     produce code that runs somewhat faster on a `Pentium' at the
     expense of more memory.

     *Warning:* if you use the `-malign-double' switch, structures
     containing the above types will be aligned differently than the
     published application binary interface specifications for the 386.

`-msvr3-shlib'
`-mno-svr3-shlib'
     Control whether GNU Pascal places uninitialized locals into `bss'
     or `data'.  `-msvr3-shlib' places these locals into `bss'.  These
     options are meaningful only on System V Release 3.

`-mno-wide-multiply'
`-mwide-multiply'
     Control whether GNU Pascal uses the `mul' and `imul' that produce
     64 bit results in `eax:edx' from 32 bit operands to do `long long'
     multiplies and 32-bit division by constants.

`-mrtd'
     Use a different function-calling convention, in which functions
     that take a fixed number of arguments return with the `ret' NUM
     instruction, which pops their arguments while returning.  This
     saves one instruction in the caller since there is no need to pop
     the arguments there.

     You can specify that an individual function is called with this
     calling sequence with the function attribute `stdcall'.  You can
     also override the `-mrtd' option by using the function attribute
     `cdecl'.

     *Warning:* this calling convention is incompatible with the one
     normally used on Unix, so you cannot use it if you need to call
     libraries compiled with the Unix compiler.

     Also, you must provide function prototypes for all functions that
     take variable numbers of arguments (including `printf'); otherwise
     incorrect code will be generated for calls to those functions.

     In addition, seriously incorrect code will result if you call a
     function with too many arguments.  (Normally, extra arguments are
     harmlessly ignored.)

`-mreg-alloc=REGS'
     Control the default allocation order of integer registers.  The
     string REGS is a series of letters specifying a register.  The
     supported letters are: `a' allocate EAX; `b' allocate EBX; `c'
     allocate ECX; `d' allocate EDX; `S' allocate ESI; `D' allocate
     EDI; `B' allocate EBP.

`-mregparm=NUM'
     Control how many registers are used to pass integer arguments.  By
     default, no registers are used to pass arguments, and at most 3
     registers can be used.  You can control this behavior for a
     specific function by using the function attribute `regparm'.

     *Warning:* if you use this switch, and NUM is nonzero, then you
     must build all modules with the same value, including any
     libraries.  This includes the system libraries and startup modules.

`-malign-loops=NUM'
     Align loops to a 2 raised to a NUM byte boundary.  If
     `-malign-loops' is not specified, the default is 2.

`-malign-jumps=NUM'
     Align instructions that are only jumped to to a 2 raised to a NUM
     byte boundary.  If `-malign-jumps' is not specified, the default is
     2 if optimizing for a 386, and 4 if optimizing for a 486.

`-malign-functions=NUM'
     Align the start of functions to a 2 raised to NUM byte boundary.
     If `-malign-jumps' is not specified, the default is 2 if optimizing
     for a 386, and 4 if optimizing for a 486.


File: gpc.info,  Node: HPPA Options,  Next: Intel 960 Options,  Prev: i386 Options,  Up: Submodel Options

HPPA Options
------------

   These `-m' options are defined for the HPPA family of computers:

`-mpa-risc-1-0'
     Generate code for a PA 1.0 processor.

`-mpa-risc-1-1'
     Generate code for a PA 1.1 processor.

`-mjump-in-delay'
     Fill delay slots of function calls with unconditional jump
     instructions by modifying the return pointer for the function call
     to be the target of the conditional jump.

`-mmillicode-long-calls'
     Generate code which assumes millicode routines cannot be reached
     by the standard millicode call sequence, linker-generated
     long-calls, or linker-modified millicode calls.  In practice this
     should only be needed for dynamicly linked executables with
     extremely large SHLIB_INFO sections.

`-mdisable-fpregs'
     Prevent floating point registers from being used in any manner.
     This is necessary for compiling kernels which perform lazy context
     switching of floating point registers.  If you use this option and
     attempt to perform floating point operations, the compiler will
     abort.

`-mdisable-indexing'
     Prevent the compiler from using indexing address modes.  This
     avoids some rather obscure problems when compiling MIG generated
     code under MACH.

`-mfast-indirect-calls'
     Generate code which performs faster indirect calls.  Such code is
     suitable for kernels and for static linking.  The fast indirect
     call code will fail miserably if it's part of a dynamically linked
     executable and in the presense of nested functions.

`-mportable-runtime'
     Use the portable calling conventions proposed by HP for ELF
     systems.

`-mgas'
     Enable the use of assembler directives only GAS understands.

`-mschedule=CPU TYPE'
     Schedule code according to the constraints for the machine type
     CPU TYPE.  The choices for CPU TYPE are `700' for 7N0 machines,
     `7100' for 7N5 machines, and `7100' for 7N2 machines.  `700' is
     the default for CPU TYPE.

     Note the `7100LC' scheduling information is incomplete and using
     `7100LC' often leads to bad schedules.  For now it's probably best
     to use `7100' instead of `7100LC' for the 7N2 machines.

`-msoft-float'
     Generate output containing library calls for floating point.
     *Warning:* the requisite libraries are not available for all HPPA
     targets.  Normally the facilities of the machine's usual C
     compiler are used, but this cannot be done directly in
     cross-compilation.  You must make your own arrangements to provide
     suitable library functions for cross-compilation.  The embedded
     target `hppa1.1-*-pro' does provide software floating point
     support.

     `-msoft-float' changes the calling convention in the output file;
     therefore, it is only useful if you compile *all* of a program with
     this option.  In particular, you need to compile `libgcc.a', the
     library that comes with GNU Pascal, with `-msoft-float' in order
     for this to work.


File: gpc.info,  Node: Intel 960 Options,  Next: DEC Alpha Options,  Prev: HPPA Options,  Up: Submodel Options

Intel 960 Options
-----------------

   These `-m' options are defined for the Intel 960 implementations:

`-mCPU TYPE'
     Assume the defaults for the machine type CPU TYPE for some of the
     other options, including instruction scheduling, floating point
     support, and addressing modes.  The choices for CPU TYPE are `ka',
     `kb', `mc', `ca', `cf', `sa', and `sb'.  The default is `kb'.

`-mnumerics'
`-msoft-float'
     The `-mnumerics' option indicates that the processor does support
     floating-point instructions.  The `-msoft-float' option indicates
     that floating-point support should not be assumed.

`-mleaf-procedures'
`-mno-leaf-procedures'
     Do (or do not) attempt to alter leaf procedures to be callable
     with the `bal' instruction as well as `call'.  This will result in
     more efficient code for explicit calls when the `bal' instruction
     can be substituted by the assembler or linker, but less efficient
     code in other cases, such as calls via function pointers, or using
     a linker that doesn't support this optimization.

`-mtail-call'
`-mno-tail-call'
     Do (or do not) make additional attempts (beyond those of the
     machine-independent portions of the compiler) to optimize
     tail-recursive calls into branches.  You may not want to do this
     because the detection of cases where this is not valid is not
     totally complete.  The default is `-mno-tail-call'.

`-mcomplex-addr'
`-mno-complex-addr'
     Assume (or do not assume) that the use of a complex addressing
     mode is a win on this implementation of the i960.  Complex
     addressing modes may not be worthwhile on the K-series, but they
     definitely are on the C-series.  The default is currently
     `-mcomplex-addr' for all processors except the CB and CC.

`-mcode-align'
`-mno-code-align'
     Align code to 8-byte boundaries for faster fetching (or don't
     bother).  Currently turned on by default for C-series
     implementations only.

`-mic-compat'
`-mic2.0-compat'
`-mic3.0-compat'
     Enable compatibility with iC960 v2.0 or v3.0.

`-masm-compat'
`-mintel-asm'
     Enable compatibility with the iC960 assembler.

`-mstrict-align'
`-mno-strict-align'
     Do not permit (do permit) unaligned accesses.

`-mold-align'
     Enable structure-alignment compatibility with Intel's gcc release
     version 1.3 (based on gcc 1.37).  Currently this is buggy in that
     `#pragma align 1' is always assumed as well, and cannot be turned
     off.


File: gpc.info,  Node: DEC Alpha Options,  Next: Clipper Options,  Prev: Intel 960 Options,  Up: Submodel Options

DEC Alpha Options
-----------------

   These `-m' options are defined for the DEC Alpha implementations:

`-mno-soft-float'
`-msoft-float'
     Use (do not use) the hardware floating-point instructions for
     floating-point operations.  When `-msoft-float' is specified,
     functions in `libgcc1.c' will be used to perform floating-point
     operations.  Unless they are replaced by routines that emulate the
     floating-point operations, or compiled in such a way as to call
     such emulations routines, these routines will issue floating-point
     operations.   If you are compiling for an Alpha without
     floating-point operations, you must ensure that the library is
     built so as not to call them.

     Note that Alpha implementations without floating-point operations
     are required to have floating-point registers.

`-mfp-reg'
`-mno-fp-regs'
     Generate code that uses (does not use) the floating-point register
     set.  `-mno-fp-regs' implies `-msoft-float'.  If the floating-point
     register set is not used, floating point operands are passed in
     integer registers as if they were integers and floating-point
     results are passed in $0 instead of $f0.  This is a non-standard
     calling sequence, so any function with a floating-point argument
     or return value called by code compiled with `-mno-fp-regs' must
     also be compiled with that option.

     A typical use of this option is building a kernel that does not
     use, and hence need not save and restore, any floating-point
     registers.


File: gpc.info,  Node: Clipper Options,  Next: H8/300 Options,  Prev: DEC Alpha Options,  Up: Submodel Options

Clipper Options
---------------

   These `-m' options are defined for the Clipper implementations:

`-mc300'
     Produce code for a C300 Clipper processor. This is the default.

`-mc400'
     Produce code for a C400 Clipper processor i.e. use floating point
     registers f8..f15.


File: gpc.info,  Node: H8/300 Options,  Next: System V Options,  Prev: Clipper Options,  Up: Submodel Options

H8/300 Options
--------------

   These `-m' options are defined for the H8/300 implementations:

`-mrelax'
     Shorten some address references at link time, when possible; uses
     the linker option `-relax'.  *Note `ld' and the H8/300:
     (ld.info)H8/300, for a fuller description.

`-mh'
     Generate code for the H8/300H.


File: gpc.info,  Node: System V Options,  Prev: H8/300 Options,  Up: Submodel Options

Options for System V
--------------------

   These additional options are available on System V Release 4 for
compatibility with other compilers on those systems:

`-Qy'
     Identify the versions of each tool used by the compiler, in a
     `.ident' assembler directive in the output.

`-Qn'
     Refrain from adding `.ident' directives to the output file (this is
     the default).

`-YP,DIRS'
     Search the directories DIRS, and no others, for libraries
     specified with `-l'.

`-Ym,DIR'
     Look in the directory DIR to find the M4 preprocessor.  The
     assembler uses this option.


File: gpc.info,  Node: Environment Variables,  Prev: Submodel Options,  Up: Invoking GPC

Environment Variables Affecting GNU Pascal
==========================================

   This section describes several environment variables that affect how
GNU CC operates.  They work by specifying directories or prefixes to use
when searching for various kinds of files.

   Note that you can also specify places to search using options such as
`-B', `-I' and `-L' (*note Directory Options::.).  These take
precedence over places specified using environment variables, which in
turn take precedence over those specified by the configuration of GNU
CC.  *Note Driver: (gcc)Driver.

`TMPDIR'
     If `TMPDIR' is set, it specifies the directory to use for temporary
     files.  GNU Pascal uses temporary files to hold the output of one
     stage of compilation which is to be used as input to the next
     stage: for example, the output of the preprocessor, which is the
     input to the compiler proper.

`GPC_EXEC_PREFIX'
     If `GPC_EXEC_PREFIX' is set, it specifies a prefix to use in the
     names of the subprograms executed by the compiler.  No slash is
     added when this prefix is combined with the name of a subprogram,
     but you can specify a prefix that ends with a slash if you wish.

     If GNU Pascal cannot find the subprogram using the specified
     prefix, it tries looking in the usual places for the subprogram.

     The default value of `GPC_EXEC_PREFIX' is `PREFIX/lib/gcc-lib/'
     where PREFIX is the value of `prefix' when you ran the `configure'
     script.

     Other prefixes specified with `-B' take precedence over this
     prefix.

     This prefix is also used for finding files such as `crt0.o' that
     are used for linking.

     In addition, the prefix is used in an unusual way in finding the
     directories to search for header files.  For each of the standard
     directories whose name normally begins with
     `/usr/local/lib/gcc-lib' (more precisely, with the value of
     `GPC_INCLUDE_DIR'), GNU Pascal tries replacing that beginning with
     the specified prefix to produce an alternate directory name.
     Thus, with `-Bfoo/', GNU Pascal will search `foo/bar' where it
     would normally search `/usr/local/lib/bar'.  These alternate
     directories are searched first; the standard directories come next.

`COMPILER_PATH'
     The value of `COMPILER_PATH' is a colon-separated list of
     directories, much like `PATH'.  GNU Pascal tries the directories
     thus specified when searching for subprograms, if it can't find the
     subprograms using `GPC_EXEC_PREFIX'.

`LIBRARY_PATH'
     The value of `LIBRARY_PATH' is a colon-separated list of
     directories, much like `PATH'.  When configured as a native
     compiler, GNU Pascal tries the directories thus specified when
     searching for special linker files, if it can't find them using
     `GPC_EXEC_PREFIX'.  Linking using GNU Pascal also uses these
     directories when searching for ordinary libraries for the `-l'
     option (but directories specified with `-L' come first).

`C_INCLUDE_PATH'
`CPLUS_INCLUDE_PATH'
`OBJC_INCLUDE_PATH'
     These environment variables pertain to particular languages.  Each
     variable's value is a colon-separated list of directories, much
     like `PATH'.  When GNU Pascal searches for header files, it tries
     the directories listed in the variable for the language you are
     using, after the directories specified with `-I' but before the
     standard header file directories.

`DEPENDENCIES_OUTPUT'
     If this variable is set, its value specifies how to output
     dependencies for Make based on the header files processed by the
     compiler.  This output looks much like the output from the `-M'
     option (*note Preprocessor Options::.), but it goes to a separate
     file, and is in addition to the usual results of compilation.

     The value of `DEPENDENCIES_OUTPUT' can be just a file name, in
     which case the Make rules are written to that file, guessing the
     target name from the source file name.  Or the value can have the
     form `FILE TARGET', in which case the rules are written to file
     FILE using TARGET as the target name.


File: gpc.info,  Node: Programming,  Next: Reference,  Prev: Invoking GPC,  Up: Top

The Programmer's Guide to GPC
*****************************

   *This chapter is under development, so don't be too excited about the
paragraph below!*

   This chapter tells you how the source of a valid GNU Pascal program
should look like.  You can use it as tutorial about the GNU Pascal
language, but since the main goal is to document all special GPC
features, implementation-dependent stuff, etc., expect a steep learning
curve.

   This chapter does *not* cover how to compile your programs and to
produce an executable--this is discussed above in *Note Invoking GPC::.

* Menu:

* Source structures::   How a GNU Pascal source file looks like.
* Data types::          Standard and non-standard data types.
* Operators::           Built-in and user-definable operators.
* Schemata::            Using Extended Pascal's "schema types".
* Pointer arithmetics:: How pointer arithmetics can be applied to
                        speed up your program.
* Type casts::          Explicit and emulated type casting in GPC.
* OOP::                 How object-orientated programming is implemented.
* Other languages::     How to share libraries with other languages.
* Run time library::    Pascal declarations for GPC's run time library.


File: gpc.info,  Node: Source structures,  Next: Data types,  Up: Programming

Source Structures
=================

   A source file accepted by GNU Pascal may contain up to one program,
zero or more ISO-style Modules, and/or zero or more UCSD-style Units,
Units and Modules can be mixed in one project.

* Menu:

* Programs::  The source structure of programs.
* Modules::   The source structure of ISO-10206 Extended Pascal Modules.
* Units::     The source structure of UCSD/Borland Pascal Units.

   One trivial example for a valid GPC source file follows.  Note that
the below may either be in one source file, or else the Unit and the
Program may be in separate source files.

     Unit Foo;
     
     Interface
     
     Procedure Hello;
     
     Implementation
     
     Procedure Hello;
     
     begin (* Hello *)
       writeln ( 'Hello, world!' );
     end (* Hello *);
     
     end.
     
     
     Program Bar;
     
     uses
       Foo;
     
     begin
       Hello;
     end.


File: gpc.info,  Node: Programs,  Next: Modules,  Up: Source structures

The Source Structure of Programs
--------------------------------

   A generic GNU Pascal program looks like the following:

     Program NAME ( Input, Output );
     
     IMPORT PART
     
     DECLARATION PART
     
     begin
       STATEMENT PART
     end.

   While the program parameters (usually `Input, Output') are
obligatory in ISO Pascal if you want to use `readln' and `writeln',
they are optional in GNU Pascal.  However if you give parameters to the
program headline, they work like ISO requires.

   The IMPORT PART consists either of an ISO-style `import'
specification or a UCSD/Borland-style `uses' clause.  While `import' is
intended to be used with interfaces exported by ISO-10206 Extended
Pascal `Modules' and `uses' is intended to be used with `Units', this
is not enforced.  (See also *Note uses::, *Note import::.)

   The DECLARATION PART consists of constant, type, variable, procedure,
and function declarations in free order.

   As an extension, GPC supports a "declaring statement" which can be
used in the statement part to declare variables (see *Note Var::).


File: gpc.info,  Node: Units,  Prev: Modules,  Up: Source structures

The Source Structure of UCSD/Borland Pascal Units
-------------------------------------------------

   A generic GNU Pascal Unit looks like the following:

     Unit NAME;
     
     Interface
     
     IMPORT PART
     
     INTERFACE PART
     
     Implementation
     
     IMPLEMENTATION PART
     
     INITIALIZATION PART
     
     end.

   The NAME of the unit should coincide with the name of the file with
the extension `.pas' or `.p' stripped.  (If not, you can tell GPC the
file name with `uses foo in 'bar.pas'', see *Note uses::.)

   The IMPORT PART is either empty or contains a `uses' clause to
import other Units.  It may also consist of an ISO-style `import'
specification.  Note that the implementation part is not preceeded by a
second import part in GPC (see *Note import::).

   The INTERFACE PART consists of constant, type, and variable
declarations, procedure and function headings which may be freely mixed.

   The IMPLEMENTATION PART is like the declaration part of a program,
but the headers of procedures and functions may be abbreviated:
Parameter lists and function return values may be omitted for
procedures and functions already declared in the interface part.

   The INITIALIZATION PART may be missing, or it may be a `begin'
followed by one or more statements, such that the Unit has a statement
part between this `begin' and the final `end'.  Alternatively, a Unit
may have ISO-style Module initializers and finalizers, see *Note to
begin::, *Note to end::.

   Note that GPC does *not* check whether all interface declarations are
resolved in the same Unit.  Procedures and functions which are in fact
not used may be omitted, and/or procedures and functions may be
implemented somewhere else, even in a different language.


File: gpc.info,  Node: Modules,  Next: Units,  Prev: Programs,  Up: Source structures

The Source Structure of ISO-10206 Extended Pascal Modules
---------------------------------------------------------

   (Under construction.  If you are familiar with Extended Pascal
Modules, please help!)


File: gpc.info,  Node: Data types,  Next: Operators,  Prev: Source structures,  Up: Programming

Data Types
==========

* Menu:

* Integer types::    GPC has *lots of* built-in Integer types
* Subrange types::   Packed and non-packed subranges
* endianness::       How integer types are stored on different machines
* alignment::        How variables are placed in memory


File: gpc.info,  Node: Integer types,  Next: Subrange types,  Up: Data types

Integer Types
-------------

   Besides `Integer', GNU Pascal supports a large zoo of integer types.
Some of them you will find in other compilers, too, but most are GNU
extensions, introduced for particular needs.  Many of these types are
synonyms for each other.  In total, GPC provides 20 built-in integer
types, plus seven families you can play with.  (Four of these
"families" are signed and unsigned, packed and unpacked Subrange types;
the others are explained below.)

* Menu:

* Natural integer types::
* Main branch integer types::
* Integer types with specified size::
* Integer types and compatibility::
* Summary of integer types::

   See also: *Note Subrange types::.


File: gpc.info,  Node: Natural integer types,  Next: Main branch integer types,  Up: Integer types

"Natural" Integer Types
.......................

   For most purposes, you will always use `Integer', a signed integer
type which has the "natural" size of such types for the machine.  On
most machines GPC runs on, this is a size of 32 bits, so `Integer'
usually has a range of `-2147483648..2147483647' (see *Note Integer::).

   If you need an unsigned integer type, the "natural" choice is
`Cardinal', also called `Word'.  Like `Integer', it has 32 bits on most
machines and thus a range of `0..4294967295' (see *Note Cardinal::,
*Note Word::).

   These natural integer types should be your first choice for best
performance.  For instance on an Intel X86 processor operations with
`Integer' usually work faster than operations with shorter integer
types like `ShortInt' or `ByteInt' (see below).


File: gpc.info,  Node: Main branch integer types,  Next: Integer types with specified size,  Prev: Natural integer types,  Up: Integer types

"Main Branch" Integer Types
...........................

   `Integer', `Cardinal', and `Word' define the three "main branches"
of GPC's integer types.  You won't always be able to deal with the
natural size; sometimes something smaller or longer will be needed.
Especially when interfacing with libraries written in other languages
such as C, you will need equivalents for their integer types.

   The following variants of `Integer', `Cardinal' and `Word' are
guaranteed to be compatible to the integer types of GNU C.  The sizes,
however, are *not* guaranteed.  They are just typical values currently
used on most platforms, but they may be actually shorter or increase in
the future.

     (signed)        (unsigned)         GNU C equivalent   typical size (bits)
     
     ByteInt    ByteCard    Byte        [un]signed char              8
     ShortInt   ShortCard   ShortWord   [unsigned] short int        16
     Integer    Cardinal    Word        [unsigned] int              32
     MedInt     MedCard     MedWord     [unsinged] long int         32
     LongInt    LongCard    LongWord    [unsinged] long long int    64

   Since we don't know whether `LongInt' will always remain the
"longest" integer type available--maybe GNU C will get `long long long
int', one day, which we will support as `LongLongInt'--we have added
the synonym `LongestInt' for the longest available singed integer type,
and the same holds for `LongestCard' and `LongestWord'.


File: gpc.info,  Node: Integer types with specified size,  Next: Integer types and compatibility,  Prev: Main branch integer types,  Up: Integer types

Integer Types with Specified Size
.................................

   In some situations you will need an integer type of a well-defined
size.  For this purpose, GNU Pascal provides tree families of signed
and unsinged integer types.  The type

       Integer ( 42 )

   is guaranteed to have a precision of 42 bits.  In a realistic
context, you will most often give a power of two as the number of bits,
and the machine you will need it on will support variables of that
size.  If this is the case, the specified precision will simultaneously
be the amount of storage needed for variables of this type.

   In short:  If you want to be sure that you have a signed integer
with 32 bits width, write `Integer ( 32 )', not just `Integer' which
might be bigger.  The same works with `Cardinal' and `Word' if you need
unsigned integer types of well-known size.


File: gpc.info,  Node: Integer types and compatibility,  Next: Summary of integer types,  Prev: Integer types with specified size,  Up: Integer types

Compatibility to other Pascal compilers
.......................................

   If you care about ISO compliance, *only* use `Integer' and subranges
of `Integer'.

   Some of GPC's non-ISO integer types exist in Borland Pascal, too:
`Byte', `ShortInt', `Word', and `LongInt'.  The sizes of these types,
however, are not the same as in Borland Pascal.  Even for `Byte' this
is not guaranteed (while probable, though).

   When designing GNU Pascal, we thought about compatibility to Borland
Pascal.  Since GNU Pascal is (at least) a 32-bit compiler, `Integer'
*must* have (at least) 32 bits.  But what to do with `Word'?  Same size
as `Integer' (like in BP) or 16 bits (like in BP)?  We decided to make
`Word' the "natural-sized" unsigned integer type, thus making it (at
least) 32 bits wide.  Similarly, we decided to give `LongInt' twice the
size of `Integer' (like in BP) rather than making it 32 bits wide (like
in BP).  So `LongInt' has 64 bits, and `ShortInt' has 16 bits on the
Intel X86 platforms.

   On the other hand, to increase compatibility to Borland Pascal and
Delphi, GPC provides the alias name `Comp' for `LongInt' (64 bits on
Intel X86) and `SmallInt' for `ShortInt' (16 bits on Intel X86).  Note
that BP treads `Comp' as a "real" type and allows assignments like
`MyCompVar:= 42.0'.  Since we don't consider this a feature, GPC does
not copy this behaviour.


File: gpc.info,  Node: Summary of integer types,  Prev: Integer types and compatibility,  Up: Integer types

Summary of Integer Types
........................

   Here is a summary of all integer types defined in GPC.  The sizes
and ranges are only *typical* values, valid on some, but not all
platforms.  Compatibility to GNU C however *is* guaranteed (to the
extend of the GNU General Public License, of course ;-).

*Note ByteInt::
     signed 8-bit integer type, `-128..128',
     compatible to `signed char' in GNU C.

*Note Byte: ByteCard
     unsigned 8-bit integer type, `0..255',
     compatible to `unsigned char' in GNU C.

*Note ShortInt::
     signed 16-bit integer type, `-32768..32767',
     compatible to `short int' in GNU C.

*Note ShortWord: ShortCard
     unsigned 16-bit integer type, `0..65535',
     compatible to `unsigned short int' in GNU C.

*Note Integer::
     signed 32-bit integer type, `-2147483648..2147483647',
     compatible to `int' in GNU C.

*Note Word: Cardinal
     unsigned 32-bit integer type, `0..4294967295',
     compatible to `unsigned int' in GNU C.

*Note MedInt::
     signed 32-bit integer type, `-2147483648..2147483647',
     compatible to `long int' in GNU C.

*Note MedWord: MedCard
     unsigned 32-bit integer type, `0..4294967295',
     compatible to `unsigned long int' in GNU C.

*Note LongInt::
     signed 64-bit integer type,
     `-9223372036854775808..9223372036854775807',
     compatible to `long long int' in GNU C.

*Note LongWord: LongCard
     unsigned 64-bit integer type, `0..18446744073709551615',
     compatible to `unsigned long long int' in GNU C.

*Note LongestInt::
     signed 64-bit integer type,
     `-9223372036854775808..9223372036854775807'.

*Note LongestWord: LongestCard
     unsigned 64-bit integer type, `0..18446744073709551615'.

*Note Comp::
     signed 64-bit integer type,
     `-9223372036854775808..9223372036854775807'.

*Note SmallInt::
     signed 16-bit integer type, `-32768..32767'.

   To specify the number of bits, use

`Integer ( N )'
     signed N-bit integer type.

`Cardinal ( N )'
     unsigned N-bit integer type.

`Word ( N )'
     unsigned N-bit integer type.

   See also: *Note Subrange types::.


File: gpc.info,  Node: Subrange types,  Next: endianness,  Prev: Integer types,  Up: Data types

Subrange Types
--------------

   GNU Pascal supports Standard Pascal's subrange types:

       Type
         MonthInt = 1..12;
         Capital = 'A'..'Z';
         ControlChar = ^A..^Z;  (* `^A' = `chr ( 1 )' is an extension *)

   To increase performance, variables of such a type are aligned in a
way which makes them fastest to access by the CPU.  As a result, `1..12'
occupies 4 bytes of storage on an Intel X86 compatible processor.

   For if you want to save storage at the expense of speed, GPC
provides a `packed' variant of these as an extension:

       Type
         MonthInt = packed 1..12;

   A variable of this type occupies the shortest possible (=
addressable) space in memory--one byte on an Intel X86 compatible
processor.

   See also: *Note packed::.


File: gpc.info,  Node: endianness,  Next: alignment,  Prev: Subrange types,  Up: Data types

Endianness
----------

   (Under construction.)


File: gpc.info,  Node: alignment,  Prev: endianness,  Up: Data types

Alignment
---------

   (Under construction.)


File: gpc.info,  Node: Operators,  Next: Schemata,  Prev: Data types,  Up: Programming

Operators
=========

   GNU Pascal supports all operators of ISO Pascal and Borland Pascal.
In addition, you can define your own operators according to the
Pascal-SC (PXSC) syntax.

* Menu:

* Built-in operators::
* User-defined operators::


File: gpc.info,  Node: Built-in operators,  Next: User-defined operators,  Up: Operators

Built-in Operators
------------------

   The following table lists all built-in GNU Pascal operators, ordered
by precedence:  `:=' has lowest precedence, `not' highest.  As usual,
the precedence of operators can be superseeded with parentheses.

     :=
     <    =    >    in   <>   >=   <=
     +    -    or   +<   -<   +>   ->
     *    /    div  mod  and  shl  shr  xor  *<   /<   *>   />
     pow  **
     not  &    @

   The Pascal-SC (PXSC) operators `+<', `-<', `+>', `->', `*<', `/<',
`*>', and `/>' are not yet implemented into GNU Pascal but may be
defined by the user (see below).


File: gpc.info,  Node: User-defined operators,  Prev: Built-in operators,  Up: Operators

User-defined Operators
----------------------

   GNU Pascal allows the definition of binary operators according to the
Pascal-SC (PXSC) syntax.  The following "scalar product" example
illustrates how to do this:

       Type
         Vector = record
           x, y: Real;
         end (* Vector *);
     
       Operator * ( a, b: Vector ) s: Real;  (* or: `= s: Real' *)
     
       begin (* Vector * Vector *)
         s:= a.x * b.x + a.y * b.y;
       ^end (* Vector * Vector *);
     
       Var
         u, v: Vector;
         a: Real;
     
       [...]
     
       a:= u * v;

   Between the closing parenthesis of the argument list and the result
variable, GPC allows an optional equal sign.  This is not allowed in
PXSC, but it is consistent with Extended Pascal's function return
variable definitions, where the equal sign is obligatory (but optional
in GPC).

   The argument types needn't be equal, and the name of the operator
may be an identifier instead of a known symbol.  You cannot define
*new* symbols in GPC.

   The PXSC operators `+>', `+<', etc. for exact numerical calculations
currently are not implemented in GPC, but you can define them.  If you
write a module which really implements these operators, please send it
to us, so we can include it into the next distribution.  Also, the
other real-type operators do *not* meet the requirements of PXSC; a
module which fixes that would be a welcome contribution.

   (And if you know more about modules in Pascal-SC than just their
existence, please contact us either!  We could probably easily
implement them if we knew how they look like.  Something quite close to
Pascal-SC modules already *is* implemented as "GNU specific modules".)


File: gpc.info,  Node: Schemata,  Next: Pointer arithmetics,  Prev: Operators,  Up: Programming

Schema Types
============

   Schemata are types that depend on one or more variables, called
"discriminants".  They are an ISO-10206 Extended Pascal extension.

       Type
         RealArray ( n: Integer ) = array [ 1..n ] of Real;

   The type `RealArray' in this example is called a Schema with the
discriminant `n'.  To declare a variable of such a type, write

       Var
         Foo: RealArray ( 42 );

   Schema-typed variables "know" about their discriminants.  They can
be accessed just like record fields:

       writeln ( Foo.n );   (* yields 42 *)

   While types of variables must always have specified discriminants
(which may be other variables), *pointers* to schema variables may be
without a discriminant:

       Type
         RealArrayPtr = ^RealArray;
     
       Var
         Bar: RealArrayPtr;

   When applying `New' to such a pointer, you must specify the intended
value of the discriminant as a parameter:

       New ( Bar, 137 );

   As a GNU extension, the above can also be written as

       Bar:= New ( RealArrayPtr, 137 );

   Schemata are not limited to arrays.  They can be of any type that
normally requires constant values in its definition, for instance
subrange types, or records containing arrays etc.  (Sets do not yet
work.)

   To finish this section, here is a somewhat exotic example:

       Type
         ColorType = ( red, green, blue );
         ColoredInteger ( Color: ColorType ) = Integer;

   A `ColoredInteger' behaves just like an ordinary integer, but it has
an additional property `Color' which can be accessed like a record
field.

       Var
         Foo: ColoredInteger ( green );
     
       [...]
     
       Foo:= 7;
       if Foo.Color = red then
         inc ( Foo, 2 )
       else
         Foo:= Foo div 3;


File: gpc.info,  Node: Pointer arithmetics,  Next: Type casts,  Prev: Schemata,  Up: Programming

Pointer Arithmetics
===================

   GPC allows to increment, decrement, compare, and subtract pointers
or to use them in `for' loops just like the C language.

       Var
         A: array [ 1..7 ] of Char;
         p, q: ^Char;
         i: Integer;
     
       [...]
     
       for p:= @A [ 1 ] to @A [ 7 ] do
         p^:= 'x';
     
       p:= @A [ 7 ];
       q:= @A [ 3 ];
       while p > q do
         begin
           p^:= 'y';
           dec ( p );
         end (* while *);
     
       p:= @A [ 7 ];
       q:= @A [ 3 ];
       i:= q - p;      (* yields 4 *)

   Incrementing a pointer by one means to increment the address it
contains by the size of the variable it is pointing to.  For typeless
pointers (`Pointer'), the address is incremented by one instead.

   Similar things hold when decrementing a pointer.

   Subtracting two pointers yields the number of variables pointed to
between both pointers, i.e. the difference of the addresses divided by
the size of the variables pointed to.  The pointers must be of the same
type.


File: gpc.info,  Node: Type casts,  Next: OOP,  Prev: Pointer arithmetics,  Up: Programming

Type Casts
==========

   In some cases, especially when interfacing with other languages,
Pascal's strong typing can be an obstacle.  To temporarily circumvent
this, GPC (and other Pascal compilers) defines explicit "type casts".

   There are two kinds of type casts, value type casts and variable type
casts.

   Value type casts

   To convert a value of one data type into another type, you can use
the target type like the name of a function that is called. The value
to be converted can be a variable or an expression.

   An example:

       Var
         Ch: Char;
         i: Integer;
     
       [...]
     
       i := Integer (Ch);

   Another, more complicated, example:

       Type
         CharPtr = ^Char;
         CharArray = array [ 0..99 ] of Char;
         CharArrayPtr = ^CharArray;
     
       Var
         Foo1, Foo2: CharPtr;
         Bar: CharArrayPtr;
     
       [...]
     
       {$X+} { We need extended syntax in order to use ``Succ'' on a pointer }
     
       Foo1 := CharPtr ( Bar );
       Foo2 := CharPtr ( Succ ( Bar ) );

   However, because of risks involved with type casts, explained below,
you should try to avoid type casts whenever possible - and it should be
possible in most cases. For instance, the first example above could use
the built-in function "Ord" instead of the type cast:

       i := Ord (Ch);

   The assignments in the second example could be written in the
following way without any type casts:

       Foo1 := @Bar^ [ 0 ];
       Foo2 := @Bar^ [ 1 ];

   Value type casting only works between certain types: either between
different ordinal types (including integer types), or between different
real types, or between different pointer types. In each case, the actual
value, i.e. the ordinal or numeric value or the address pointed to,
respectively, is preserved in the cast.

   Note: It is also possible to cast from an integer into a real type.
This is a consequence of the fact that integer values are generally
automatically converted to real values when needed.

   Note: In the case of pointers, a warning is issued if the
dereferenced target type requires a bigger alignment than the
dereferenced source type (see *Note alignment::).

   Variable type casts

   It is also possible to temporarily change the type of a variable,
without converting its contents in any way. This is called variable
type casting.

   The syntax is the same as for value type casting. This can be
confusing, as the example below shows.

   The type-casted variable is still the same variable (memory location)
as the original one, just with a different type. Outside of the type
cast, the variable keeps its original type.

   There are some important differences between value and variable type
casting:

   *   Variable type casting only works on variables, not on
     expressions.

   *   The result of a variable type casting is still a variable.
     Especially, it can be used on the left side of an assignment   (as
     a so-called "lvalue"), or passed by reference to a procedure.

   *   No values are converted. The contents of the variable, seen as a
     raw   bit pattern, are just interpreted according to the new type.
     In many   cases, this does not make a big difference, e.g. the
     same ordinal   values of different ordinal types have the same bit
     pattern (provided,   the types have the same size), and similarly
     for different pointer types.    However, there are cases where it
     does make a difference, most notably   the completely different
     internal representation of integer and real   types. This is
     demonstrated in the following example, admittedly a   very
     constructed example, by using an integer and a real type of the
     same size and trying to cast between them.

   *   Because bit patterns are just interpreted differently, the
     source and   target type must have the same size. If this is not
     the case, GPC will   give a warning. (@error? see below)

   *   Beware: Variable type casts might have unexpected effects on
     different   platforms since you cannot rely on a specific way the
     data is stored   (e.g. see *Note endianness::).

       program TypeCastingTraps;
     
       { Declare a real type and an integer type of the same size, and some
         variables of these types we will need. }
     
       Type
         RealType    = ShortReal;
         IntegerType = Integer ( BitSizeOf ( RealType ) );
     
       Var
         i, i1, i2, i3, i4, i5: IntegerType;
         r, r1, r2, r3, r4:     RealType;
     
       begin
     
         { First part: Casting integer into real types. }
     
         { Start with some integer value }
         i := 42;
     
         { First attempt to cast. Here, an lvalue is casted, so this must
           be a variable type cast. Therefore, the bit pattern of the value
           of i is transferred unchanged into r1 which results in a silly
           value of r1. }
         IntegerType (r1) := i;
     
         { Second try. Here we cast an expression -- though a trivial one --,
           rather than a variable. So this can only be a value type cast.
           Therefore, the numeric value is preserved, i.e. r2 = 42.0 . }
         r2 := RealType (i+0);
     
         { Third way. In this last example, a variable is casted, and the
           result is used as an expression, not as an lvalue. So this
           could be either a value or variable type cast. However, there
           is a rule that value type casting is preferred if possible.
           So r3 will contain the correct numeric value, too. }
         r3 := RealType (i);
     
         { Of course, you do not need any casts at all here. A simple
           assignment will work because of the automatic conversion from
           integer to real types. So r4 will also get the correct result. }
         r4 := i;
     
         { Now the more difficult part: Casting real into integer types. }
     
         { Start with some real value. }
         r := 41.9;
     
         { Like the first attempt above, this one does a variable type cast,
           preserving bit patterns, and leaving a silly value in i1. }
         RealType (i1) := r;
     
         { The second try from above does not work, because an expression of
           type real is to be casted into an integer which is not allowed. }
         { i2 := IntegerType (r+0); }
     
         { Third way. This looks just like the third way in the first part
           which was a value type cast.
           But -- surprise! Since value type casting is not possible from
           real into integer, this really does a variable type casting,
           and the value of i3 is silly again! This difference in behaviour
           shows some of the hidden traps in type casting. }
         i3 := IntegerType (r);
     
         { As often, it is possible to avoid type casts altogether and
           convert real types into integers easily by other means, i.e. by
           using the built-in functions ``Round'' or ``Trunc'', depending
           on the mode of rounding one wants. }
         i4 := Round (r); { 42 }
         i5 := Trunc (r); { 41 }
     
       end.

   When dealing with objects (see *Note OOP::), it is often
necessary--and safe--to cast a pointer to an object into a pointer to a
more specialized (derived) object.  In future releases, GPC will
provide an operator `as' for a safer approach to this problem.

   See also: *Note absolute::, *Note alignment::, *Note endianness::,
*Note OOP::,           *Note ord::, *Note chr::, *Note round::, *Note
trunc::.


File: gpc.info,  Node: OOP,  Next: Other languages,  Prev: Type casts,  Up: Programming

Object-orientated Programming
=============================

   GNU Pascal follows the object model of Borland Pascal 7.0.  The ANSI
draft Object Pascal language and the Delphi language (also called
"Object Pascal" by Borland) are currently not implemented, but planned
for future versions of GPC.

   The syntax for an object type declaration is as follows:

       Type
         fooParentPtr = ^fooParent;
         fooPtr = ^foo;
     
         fooParent = object
           Destructor Fini; virtual;
           Procedure bar ( c: Real ); virtual;
           Procedure baz ( b, a, z: Char );  (* not virtual *)
         end (* FooParent *)
     
         foo = object ( fooParent )
           x, y: Integer;
           Constructor Init ( a, b: Integer );
           Destructor Fini; virtual;
           z: Real;
           Procedure bar ( c: Real ); virtual;  (* overrides `fooParent.bar' *)
           Function baz: Boolean;  (* new function *)
         end (* foo *);

   Remarks:

   * Data fields and methods can be mixed.

   * GPC currently does not support `private' declarations and such.

   * Constructors and destructors are ordinary functions, internally.
     When a constructor is called, GPC creates some inline code to
     initialize the object; destructors do nothing special.

   * Currently, the `gpc1' compiler does not check whether all declared
     methods are really implemented; the linker does check this.

   A pointer to `fooParent' may be assigned the address of a `foo'
object.  A `fooParent' formal `Var' parameter may get a `foo' object as
the actual parameter.  In such cases, a call to a `virtual' method
calls the child's method, whereas a call to a non-`virtual' method
selects the parent's one:

       Var
         MyFooParent: fooParentPtr;
         SomeFoo: foo;
     
       [...]
     
       SomeFoo.Init ( 4, 2 );
       MyFooParent:= @SomeFoo;
       MyFooParent^.bar ( 3.14 );  (* calls `foo.bar' *)
       MyFooParent^.baz ( 'b', 'a', 'z' );  (* calls `fooParent.baz' *)
       if SomeFoo.baz then  (* calls `foo.baz' *)
         writeln ( 'Baz!' );

   In a method, an overwritten method of a parent object can be called
either prefixing it with the parent type name, or using the keyword
`inherited':

       Procedure foo.bar ( c: Real );
     
       begin (* foo.bar *)
         z:= c;
         inherited bar ( z );  (* Or: fooParent.bar ( z ) *)
       end (* foo.bar *);

   Use `fooParent.bar ( z )' if you want to be sure that *this* method
is called, even if somebody decides not to derive `foo' directly from
`fooParent' but to have some intermediate object.  If you want to call
the method `bar' of the immediate parent--whether it be `fooParent' or
whatever--use `inherited bar ( z )'.

   To allocate an object on the heap, use `New' in one of the following
manners:

       Var
         MyFoo: fooPtr;
     
       [...]
     
       New ( MyFoo, Init ( 4, 2 ) );
     
       MyFooParent:= New ( fooPtr, Init ( 4, 2 ) );

   The second possibility has the advantage that `MyFoo' needn't be a
`fooPtr' but can also be a `fooParentPtr', i.e. a pointer to an
ancestor of `foo'.

   Destructors can and should be called within Dispose:

       Dispose ( MyFooParent, Fini );


File: gpc.info,  Node: Other languages,  Next: Run time library,  Prev: OOP,  Up: Programming

Interfacing with Other Languages
================================

   The standardized GNU compiler back-end makes it relatively easy to
share libraries between GNU Pascal and other GNU compilers.  On
UNIX-like platforms (*not* on MS-DOS-like platforms), the GNU compiler
back-end usually complies to the standards defined for that system, so
communication with other compilers should be easy, too.

   In this chapter we discuss how to import libraries written in other
languages, and how to import libraries written in GNU Pascal from other
languages.  While the examples will specialize to compatibility to GNU
C, generalization is straightforward if you are familiar with the other
language in question.

* Menu:

* Importing from other languages::
* Exporting to other languages::


File: gpc.info,  Node: Importing from other languages,  Next: Exporting to other languages,  Up: Other languages

Importing Libraries from Other Languages
----------------------------------------

   To use a function written in another language, you need to provide
an external declaration for it--either in the program, or in the
interface part of a Unit, or an Interface Module.

   Let's say you want to use the following C library from Pascal:

       /* foobar.c */
     
       #include <unistd.h>
     
       int foo = 1;
     
       void bar ( void )
       {
         sleep ( foo );
       } /* bar */
     
     
       /* foobar.h */
     
       extern int foo;
       extern void bar ( void );

   Then your program can look like this:

       Program TestFoo;
     
       (*$L foobar.c *)  (* Or: `foobar.o' if you don't have the source *)
     
       Var
         foo: asmname 'foo' Integer;
     
       Procedure Bar; asmname 'bar';
     
       begin
         foo:= 42;
         Bar;  (* Take a break :*)
       end.

   Or, if you want to provide a `FooBar' Unit:

       Unit FooBar;
     
       Interface
     
       Var
         foo: asmname 'foo' Integer;
     
       Procedure Bar; asmname 'bar';
     
       Implementation
     
       (* empty *)
     
       end.

   You can either link your program manually with `foobar.o' or put a
compiler directive `(*$L foobar.o *)' into your program (planned for
Units, too), and then GPC cares about the linking.  If you have the
source of the "FooBar" library (you always have it if it is Free
Software), you can even write `(*$L foobar.c *)' in the program (like
above).  Then GPC will also link with `foobar.o', but in addition GPC
will run the C compiler whenever `foobar.c' has changed if `--automake'
is given, too.

   While it is convenient for most applications, there is no must to
give the C function `bar' the name `Bar' in Pascal; you can name it as
you like.

   For external functions completely written in lowercase there is the
shortcut `C' or `C_language' for `asmname 'bar''.  For external
functions written with one uppercase letter and the others in
lowercase, you can use `external' or `extern' instead of `asmname
'Bar''.  Since GPC internally converts all identifiers to this notation,
`external' is the natural choice when importing other Pascal functions.

   *Caution:* This syntax (`C', `asmname' and such) is subject to
change, especially for variables.

   Some libraries provide a `main' function and require your program's
"main" to be named differently.  To achive this with GPC, invoke it
with an option `--gpc-main="GPCmain"' (where "GPCmain" is an example
how you might want to name the program).  You can also write it into
your source as a directive `(*$pascal-main="GPCmain" *)'.


File: gpc.info,  Node: Exporting to other languages,  Prev: Importing from other languages,  Up: Other languages

Exporting GPC Libraries to Other Languages
------------------------------------------

   The `.o' files produced by GPC are in the same format as those of all
other GNU compilers, so there is no problem in writing libraries for
other languages in Pascal.  To use them, you will need to write kind of
interface--a header file in C.  However there are some things to take
into account, especially if your Pascal Unit exports objects:

   * By default, GPC capitalizes the first letter of each identifier, so
     `Procedure FooBAR' must be imported as `extern void Foobar()' from
     C.

   * If you want to specify the external name separately, use `asmname':

            Procedure FooBAR; asmname 'FooBAR';
            (* Works like a `forward' declaration *)
          
            Procedure FooBAR;
          
            begin (* FooBAR *)
              writeln ( 'FooBAR' );
            end (* FooBAR *);

     This one can be imported from C with `extern void FooBar()'.

   * Objects are "records" internally.  They have an implicit `vmt'
     field which contains a pointer to the "virtual method table".
     This table is another record of the following structure:

            Type
              SizeInt = Integer ( BitSizeOf ( Pointer ) );
          
              VMT = record
                ObjectSize: SizeInt;  (* Size of object in bytes. *)
                NegObjectSize: SizeInt;  (* Its negative. *)
                Fun: array [ 1..n ] of Procedure;
                  (* Pointers to the virtual functions. *)
              end (* VMT *);

     You can call a virtual method of an object from C if you
     explicitly declare this `struct' and explicitly dereference the
     `Fun' array.  The VMT of an object `FooBAR' is an external (in C
     sense) variable `vmt_Foobar' internally.

   * Methods of objects are named `Myobject_Mymethod' (with exactly two
     capital letters) internally.

   * The main program is just another procedure; `Program FooBAR'
     produces `Procedure FooBAR; asmname 'program_Foobar'' (without
     parameters) internally.  There is a separate function `main' which
     stores the command-line arguments in global variables and then
     calls this "main procedure".

   * If you want to put a program in a library for some reason, and you
     want to give the `main' program an internal name different from
     `main', call GPC with the option `--pascal-main="GPCmain"' (see
     previous subsection).


File: gpc.info,  Node: Run time library,  Prev: Other languages,  Up: Programming

Run Time Library--Pascal Declarations
=====================================

   Below is a pascal source of the declarations in GPC's run time
library.  A file `gpc.pas' with the same contents is included in the GPC
distribution in the same directory as `libgcc.a'.  (To find out the
correct directory for your installation type `gpc
-print-libgcc-file-name' at the command prompt.)

     {
     Copyright (C) 1998-99 Free Software Foundation, Inc.
     
     Author: Frank Heckenbach <frank@pascal.gnu.de>
     
     Pascal declarations of the GPC RTS that are visible to each program.
     
     This unit contains Pascal declarations of many RTS routines which can
     be called from programs. Some other declarations that should not
     normally be called from programs, are contained in the unit `Internal'.
     Some of these routines correspond to functions built into the compiler,
     such as most of the file operations; the declarations here should only
     be used if the built-in functions are not applicable for some reason.
     Other routines, like many file name and string routines, are not built
     in, so the declarations from this unit can be used. Don't copy the
     declarations from this unit into your programs, but rather include
     this unit with a `uses' statement. The reason is that the internal
     declarations, e.g. the `asmnames', may change, and this unit will be
     changed accordingly. @@In the future, this unit might be included into
     every program automatically, so there will be no need for a `uses'
     statement to make the declarations here available.
     
     Note about `protected var' parameters:
     Since const parameters in GPC can be passed by value OR by reference
     internally, possibly depending on the system, `const foo*' parameters
     to C functions *cannot* reliably declared as `const' in Pascal.
     However, Extended Pascal's `protected var' can be used since this
     guarantees passing by reference.
     
     Note about the `GPC_' prefix:
     This is inserted so that some identifiers don't conflict with the
     built-in ones. Sometimes, the built-in ones do exactly the same as
     the ones declared here, but often enough, they contain some "magic",
     so they should be used instead of the plain declarations here.
     In general, routines with a `GPC_' prefix should not be called from
     programs. They are subject to change or disappering in future GPC
     versions.
     
     This file is part of GNU Pascal Library. The GNU Pascal Library is free
     software; you can redistribute it and/or modify it under the terms of
     the GNU Library General Public License as published by the Free Software
     Foundation; either version 2 of the License, or (at your option) any
     later version.
     
     The GNU Pascal Library is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     Library General Public License for more details.
     
     You should have received a copy of the GNU Library General Public
     License along with the GNU Pascal Library; see the file COPYING.LIB.  If
     not, write to the Free Software Foundation, Inc., 675 Mass Ave,
     Cambridge, MA 02139, USA.
     }
     
     unit GPC;
     
     interface
     
     type
       AnyFile = Text; (*@@ create `AnyFile' parameters*)
     
     const
       MaxLongInt = High (LongInt);
     
       { Maximum size of a variable }
       MaxVarSize = MaxInt;
     
     { ====================== RUNTIME ERROR HANDLING ETC. ====================== }
     
     type
       PCStrings = ^TCStrings;
       TCStrings = array [0 .. MaxVarSize] of CString;
     
     var
       ProcessID   : asmname '_p_pid'  Integer;
       CParamCount : asmname '_p_argc' Integer;
       CParameters : asmname '_p_argv' PCStrings;
       Environment : asmname '_p_envp' PCStrings;
     
     { Error handling functions, from error.pas }
     
     var
       { BP compatible InOutRes variable }
       GPC_InOutRes : asmname '_p_inoutres' Integer;
     
       { CString parameter to some error messages, NOT the text of the error
         message (this can be obtained with GetErrorMessage) }
       GPC_InOutResStr : asmname '_p_inoutres_str' CString;
     
       { Error number (after runtime error) or exit status (after Halt) or
         0 (during program run and after succesful termination). }
       ExitCode : asmname '_p_exitcode' Integer;
     
       { Non-nil after runtime error, nil otherwise. Does not give the actual
         address of the code where the error occurred. }
       ErrorAddr : asmname '_p_erroraddr' Pointer;
     
     function  GetErrorMessage                 (n : Integer) : CString;                   asmname '_p_errmsg';
     function  GetCheckErrorMessage            (n : Integer; Format : CString) : CString; asmname '_p_check_errmsg';
     procedure StartRuntimeMessage;                                                       asmname '_p_start_message';
     procedure StartInternalError;                                                        asmname '_p_start_internal_error';
     procedure EndRuntimeError                 (n : Integer);                             asmname '_p_end_error';
     function  StartRuntimeWarning : Boolean;                                             asmname '_p_start_warning';
     procedure EndRuntimeWarning;                                                         asmname '_p_end_warning';
     procedure RuntimeError                    (n : Integer);                             asmname '_p_error';
     procedure RuntimeErrorInteger             (n : Integer; i : MedInt);                 asmname '_p_error_integer';
     procedure RuntimeErrorCString             (n : Integer; s : CString);                asmname '_p_error_string';
     procedure InternalError                   (n : Integer);                             asmname '_p_internal_error';
     procedure InternalErrorInteger            (n : Integer; i : MedInt);                 asmname '_p_internal_error_integer';
     procedure RuntimeWarning                  (Message : CString);                       asmname '_p_warning';
     procedure RuntimeWarningInteger           (Message : CString; i : MedInt);           asmname '_p_warning_integer';
     procedure RuntimeWarningCString           (Message : CString; s : CString);          asmname '_p_warning_string';
     
     { Internal routine for `RunError' calls from the program }
     procedure GPC_RunError                    (n : Integer);                             asmname '_p_runerror';
     
     procedure StartTempIOError;                                                          asmname '_p_start_temp_io_error';
     function  EndTempIOError : Integer;                                                  asmname '_p_end_temp_io_error';
     procedure IOError                         (n : Integer);                             asmname '_p_io_error';
     procedure IOErrorCString                  (n : Integer; s : CString);                asmname '_p_io_error_string';
     function  GPC_IOResult : Integer;                                                    asmname '_p_ioresult';
     function  GetIOErrorMessage : CString;                                               asmname '_p_get_io_error_message';
     procedure CheckInOutRes;                                                             asmname '_p_check_inoutres';
     procedure GPC_Halt (aExitCode : Integer);                                            asmname '_p_halt';
     
     { For GNU malloc }
     procedure HeapWarning                     (s : CString);                             asmname '_p_heap_warning';
     
     { For signal handlers }
     procedure PrintMessage (Message : CString; n : Integer; Warning : Boolean);          asmname '_p_prmessage';
     
     { =========================== MEMORY MANAGEMENT =========================== }
     
     { `MoveLeft', `MoveRight' and `Move' transfer procedures, from move.pas }
     
     procedure GPC_MoveLeft  (const Source; var Dest; Count : SizeType); asmname '_p_moveleft';
     procedure GPC_MoveRight (const Source; var Dest; Count : SizeType); asmname '_p_moveright';
     procedure GPC_Move      (const Source; var Dest; Count : SizeType); asmname '_p_move';
     
     function  MemCmp  (const s1, s2; Size : SizeType) : Integer; asmname 'memcmp';
     function  MemComp (const s1, s2; Size : SizeType) : Integer; asmname 'memcmp';
     
     { Heap manipulation, from heap.c }
     
     { GPC implements both Mark/Release and Dispose. Both can be mixed freely
       in the same program. Dispose should be preferred, since it's faster. }
     
     type
       GetMemType  = ^function (Size : SizeType) : Pointer;
       FreeMemType = ^procedure (aPointer : Pointer);
     
     var
       GetMemPtr  : asmname '_p_getmem_ptr'  GetMemType;
       FreeMemPtr : asmname '_p_freemem_ptr' FreeMemType;
     
     { GetMemPtr and FreeMemPtr point to these routines by default }
     function  Default_GetMem  (Size : SizeType) : Pointer; asmname '_p_default_malloc';
     procedure Default_FreeMem (aPointer : Pointer);        asmname 'free';
     
     { GPC_GetMem and GPC_FreeMem call the actual routines through GetMemPtr and FreeMemPtr }
     function  GPC_GetMem  (Size : SizeType) : Pointer;     asmname '_p_malloc';
     procedure GPC_FreeMem (aPointer : Pointer);            asmname '_p_free';
     
     { GPC_New and GPC_Dispose call GPC_GetMem and GPC_FreeMem, but also do the
       stuff necessary for Mark and Release. Therefore, GPC_GetMem and GPC_FreeMem
       should not be called directly when using Mark and Release. GetMem and
       FreeMem in a Pascal program will call GPC_New and GPC_Dispose internally,
       not GPC_GetMem and GPC_FreeMem. }
     function  GPC_New     (Size : SizeType) : Pointer;     asmname '_p_new';
     procedure GPC_Dispose (aPointer : Pointer);            asmname '_p_dispose';
     
     { ReleaseF will return the number of pointers released. While Release
       discards this information, it can be used e.g. during debugging to
       verify that all allocated memory blocks are correctly disposed, and
       no memory leaks exist. }
     procedure GPC_Mark    (var aPointer : Pointer);        asmname '_p_mark';
     function  ReleaseFunc (aPointer : Pointer) : Integer;  asmname '_p_release';
     
     { C heap management routines. NOTE: when using Release, CFreeMem must not
       be used but for pointers allocated by CGetMem. }
     function  CGetMem     (Size : SizeType) : Pointer;                     asmname 'malloc';
     procedure CFreeMem    (aPointer : Pointer);                            asmname 'free';
     function  ReAlloc     (aPointer : Pointer; Size : SizeType) : Pointer; asmname 'realloc';
     
     { Routines to handle endianness, from endian.pas }
     
     { Boolean constants about endianness and alignment }
     
     const
       Bits_Big_Endian  = {$ifdef __BITS_LITTLE_ENDIAN__} False
                          {$else}{$ifdef __BITS_BIG_ENDIAN__} True
                          {$else}{$error Bit endianness is not defined!}
                          {$endif}{$endif};
     
       Bytes_Big_Endian = {$ifdef __BYTES_LITTLE_ENDIAN__} False
                          {$else}{$ifdef __BYTES_BIG_ENDIAN__} True
                          {$else}{$error Byte endianness is not defined!}
                          {$endif}{$endif};
     
       Words_Big_Endian = {$ifdef __WORDS_LITTLE_ENDIAN__} False
                          {$else}{$ifdef __WORDS_BIG_ENDIAN__} True
                          {$else}{$error Word endianness is not defined!}
                          {$endif}{$endif};
     
       Need_Alignment   = {$ifdef __NEED_ALIGNMENT__} True
                          {$else} False {$endif};
     
     { Convert single variables from or to little or big endian format.
       For structures, this has to be done for each component separately!
       Currently, ConvertFromFooEndian and ConvertToFooEndian are the same, but
       this might not be the case on middle-endian machines. So it's better to
       provide and use different names. }
     procedure ReverseBytes            (var Buf; Count : SizeType);                                asmname '_p_reversebytes';
     procedure ConvertFromLittleEndian (var Buf; Count : SizeType);                                asmname '_p_convertlittleendian';
     procedure ConvertFromBigEndian    (var Buf; Count : SizeType);                                asmname '_p_convertbigendian';
     procedure ConvertToLittleEndian   (var Buf; Count : SizeType);                                asmname '_p_convertlittleendian';
     procedure ConvertToBigEndian      (var Buf; Count : SizeType);                                asmname '_p_convertbigendian';
     
     { Combine the conversion with file block routines }
     function  BlockReadLittleEndian   (var aFile : File; var   Buf; Count : SizeType) : SizeType; asmname '_p_blockread_littleendian';
     function  BlockReadBigEndian      (var aFile : File; var   Buf; Count : SizeType) : SizeType; asmname '_p_blockread_bigendian';
     function  BlockWriteLittleEndian  (var aFile : File; const Buf; Count : SizeType) : SizeType; asmname '_p_blockwrite_littleendian';
     function  BlockWriteBigEndian     (var aFile : File; const Buf; Count : SizeType) : SizeType; asmname '_p_blockwrite_bigendian';
     
     { ======================== STRING HANDLING ROUTINES ======================= }
     
     { String handling routines, from gstrings.pas }
     
     type
       TChars = packed array [1 .. 1] of Char;
       PChars = ^TChars;
     
       GPC_PString = ^GPC_String;
       GPC_String (Capacity : Cardinal) = record
         Length : 0 .. Capacity;
         Chars  : packed array [1 .. Capacity + 1] of Char
       end;
     
       StringObject = object { Abstract }
         function  GetCapacity : Integer;           virtual;
         procedure SetLength (NewLength : Integer); virtual;
         function  GetLength : Integer;             virtual;
         function  GetFirstChar : PChars;           virtual;
       end;
     
       (*@@ AnyString parameters are not yet implemented, the following is only a draft*)
       AnyStringType = (AnyStringLong,
                        AnyStringUndiscriminated,
                        AnyStringShort,
                        AnyStringFixed,
                        AnyStringCString,
                        AnyStringObject);
     
       (*@@ only formally for now*)UndiscriminatedString = ^String;
     
       { When a const or var AnyString parameter is passed, internally these
         records are passed as const parameters. Value AnyString parameters are
         passed like value string parameters. }
       ConstAnyString = record
         Length : Integer;
         Chars  : PChars
       end;
     
       VarAnyString = record
         Capacity : Integer;
         Chars    : PChars;
         Truncate : Boolean;
       case StringType            : AnyStringType of
         AnyStringLong            : (PLongLength            : ^Integer);
         AnyStringUndiscriminated : (PUndiscriminatedString : ^UndiscriminatedString);
         AnyStringShort           : (PShortLength           : ^Byte);
         AnyStringFixed           : (CurrentLength          : Integer);
         AnyStringObject          : (PStringObject          : ^StringObject)
       end;
     
     { TString is a string type that is used for function results and local
       variables, as long as undiscriminated strings are not allowed there.
       The default size of 2048 characters should be enough for file names
       on any system, but can be changed when necessary. This should be at
       least as big as MAXPATHLEN. }
     
     const
       TStringSize = 2048;
       SpaceCharacters = [' ', #9];
     
     type
       TString    = String (TStringSize);
       TStringBuf = packed array [0 .. TStringSize] of Char;
       PString    = ^String;
       CharSet    = set of Char;
     
     function  GPC_UpCase      (ch : Char) : Char;                                    asmname '_p_gpc_upcase';
     function  GPC_LoCase      (ch : Char) : Char;                                    asmname '_p_gpc_locase';
     function  BP_UpCase       (ch : Char) : Char;                                    asmname '_p_bp_upcase';
     function  BP_LoCase       (ch : Char) : Char;                                    asmname '_p_bp_locase';
     
     procedure UpCaseString    (var s : String);                                      asmname '_p_upcase_string';
     procedure LoCaseString    (var s : String);                                      asmname '_p_locase_string';
     function  UpCaseStr       (const s : String) : TString;                          asmname '_p_upcase_str';
     function  LoCaseStr       (const s : String) : TString;                          asmname '_p_locase_str';
     
     function  Pos             (const SubStr, Str : String) : Integer;                asmname '_p_pos';
     function  LastPos         (const SubStr, Str : String) : Integer;                asmname '_p_lastpos';
     function  CharPos         (const Chars : CharSet; const Str : String) : Integer; asmname '_p_charpos';
     function  LastCharPos     (const Chars : CharSet; const Str : String) : Integer; asmname '_p_lastcharpos';
     
     function  PosFrom         (const SubStr, Str : String; From : Integer) : Integer;                asmname '_p_posfrom';
     function  LastPosTill     (const SubStr, Str : String; Till : Integer) : Integer;                asmname '_p_lastpostill';
     function  CharPosFrom     (const Chars : CharSet; const Str : String; From : Integer) : Integer; asmname '_p_charposfrom';
     function  LastCharPosTill (const Chars : CharSet; const Str : String; Till : Integer) : Integer; asmname '_p_lastcharpostill';
     
     function  IsPrefix        (const Prefix, s : String) : Boolean;                  asmname '_p_isprefix';
     function  IsSuffix        (const Suffix, s : String) : Boolean;                  asmname '_p_issuffix';
     
     function  StrLen          (Src : CString) : SizeType;                            asmname '_p_strlen';
     function  StrEnd          (Src : CString) : CString;                             asmname '_p_strend';
     function  StrDup          (Src : CString) : CString;                             asmname '_p_strdup';
     function  StrNew          (Src : CString) : CString;                             asmname '_p_strdup';
     procedure StrDispose      (s : CString);                                         asmname '_p_dispose';
     function  StrCmp          (s1, s2 : CString) : Integer;                          asmname '_p_strcmp';
     function  StrComp         (s1, s2 : CString) : Integer;                          asmname '_p_strcmp';
     function  StrLCmp         (s1, s2 : CString; MaxLen : SizeType) : Integer;       asmname '_p_strlcmp';
     function  StrLComp        (s1, s2 : CString; MaxLen : SizeType) : Integer;       asmname '_p_strlcmp';
     function  StrCaseCmp      (s1, s2 : CString) : Integer;                          asmname '_p_strcasecmp';
     function  StrIComp        (s1, s2 : CString) : Integer;                          asmname '_p_strcasecmp';
     function  StrLCaseCmp     (s1, s2 : CString; MaxLen : SizeType) : Integer;       asmname '_p_strlcasecmp';
     function  StrLIComp       (s1, s2 : CString; MaxLen : SizeType) : Integer;       asmname '_p_strlcasecmp';
     function  StrCpy          (Dest, Source : CString) : CString;                    asmname '_p_strcpy';
     function  StrCopy         (Dest, Source : CString) : CString;                    asmname '_p_strcpy';
     function  StrECpy         (Dest, Source : CString) : CString;                    asmname '_p_strecpy';
     function  StrECopy        (Dest, Source : CString) : CString;                    asmname '_p_strecpy';
     function  StrLCpy         (Dest, Source : CString; MaxLen : SizeType) : CString; asmname '_p_strlcpy';
     function  StrLCopy        (Dest, Source : CString; MaxLen : SizeType) : CString; asmname '_p_strlcpy';
     function  StrMove         (Dest, Source : CString; Count : SizeType) : CString;  asmname '_p_strmove';
     function  StrCat          (Dest, Source : CString) : CString;                    asmname '_p_strcat';
     function  StrLCat         (Dest, Source : CString; MaxLen : SizeType) : CString; asmname '_p_strlcat';
     function  StrScan         (Src : CString; Ch : Char) : CString;                  asmname '_p_strscan';
     function  StrRScan        (Src : CString; Ch : Char) : CString;                  asmname '_p_strrscan';
     function  StrPos          (Str, SubStr : CString) : CString;                     asmname '_p_strpos';
     function  StrRPos         (Str, SubStr : CString) : CString;                     asmname '_p_strrpos';
     function  StrCasePos      (Str, SubStr : CString) : CString;                     asmname '_p_strcasepos';
     function  StrRCasePos     (Str, SubStr : CString) : CString;                     asmname '_p_strrcasepos';
     function  StrUpper        (s : CString) : CString;                               asmname '_p_strupper';
     function  StrLower        (s : CString) : CString;                               asmname '_p_strlower';
     function  StrEmpty        (s : CString) : Boolean;                               asmname '_p_strempty';
     
     function  NewCString      (const Source : String) : CString;                     asmname '_p_newcstring';
     function  StrPCopy        (Dest : CString; const Source : String) : CString;     asmname '_p_strpcopy';
     procedure StrCCopy        (Source : CString; var Dest : String);                 asmname '_p_strccopy';
     
     function  NewString       (const s : String) : PString;                          asmname '_p_newstring';
     procedure DisposeString   (p : PString);                                         asmname '_p_dispose';
     
     procedure SetString       (var s : String; Buffer : PChar; Count : Integer);     asmname '_p_set_string';
     function  StringOfChar    (Ch : Char; Count : Integer) = s : TString;            asmname '_p_string_of_char';
     
     procedure TrimLeft        (var s : String);                                      asmname '_p_trimleft';
     procedure TrimRight       (var s : String);                                      asmname '_p_trimright';
     procedure TrimBoth        (var s : String);                                      asmname '_p_trimboth';
     function  TrimLeftStr     (const s : String) : TString;                          asmname '_p_trimleft_str';
     function  TrimRightStr    (const s : String) : TString;                          asmname '_p_trimright_str';
     function  TrimBothStr     (const s : String) : TString;                          asmname '_p_trimboth_str';
     
     { Internal routines for the string operators }
     
     { Compare strings for equality without padding }
     function  StrEQ (s1 : PChar; Length1 : Integer; s2 : PChar; Length2 : Integer) : Boolean;    asmname '_p_eq';
     
     { Compare strings for `less-than' without padding }
     function  StrLT (s1 : PChar; Length1 : Integer; s2 : PChar; Length2 : Integer) : Boolean;    asmname '_p_lt';
     
     { Compare strings for equality, padding the shorter string with spaces }
     function  StrEQPad (s1 : PChar; Length1 : Integer; s2 : PChar; Length2 : Integer) : Boolean; asmname '_p_str_eq';
     
     { Compare strings for `less-than', padding the shorter string with spaces }
     function  StrLTPad (s1 : PChar; Length1 : Integer; s2 : PChar; Length2 : Integer) : Boolean; asmname '_p_str_lt';
     
     { Internal routine for Index/Pos }
     function  StrIndex (s1 : PChar; Length1 : Integer; s2 : PChar; Length2 : Integer) : Integer; asmname '_p_index';
     
     { Internal routine for Trim }
     function  StrTrim (Src : PChar; SrcLength : Integer; Dest : PChar) : Integer; asmname '_p_trim';
     
     { Internal routine for SubStr/Copy }
     function  SubStr (Src : PChar; SrcLength, Position, Count : Integer; Dest : PChar; Truncate : Boolean) : Integer; asmname '_p_substr';
     
     function  GetStringCapacity (const s : String) : Integer;                        asmname '_p_get_string_capacity';
     
     procedure GPC_Insert      (const Source: String; var Dest : String;
                                Index : Integer; Truncate : Boolean);                 asmname '_p_insert';
     procedure GPC_Delete      (var s : String; Index, Count : Integer);              asmname '_p_delete';
     
     { Under development }
     function VarAnyStringLength (var s : VarAnyString) : Integer; asmname '_p_var_anystring_length';
     function VarAnyStringSetLength (var s : VarAnyString; NewLength : Integer) : Integer; asmname '_p_var_anystring_setlength';
     procedure AnyStringTFDD_Reset (var f : AnyFile; var Buf : ConstAnyString); asmname '_p_anystring_tfdd_reset';
     procedure AnyStringTFDD_Rewrite (var f : AnyFile; var Buf : VarAnyString); asmname '_p_anystring_tfdd_rewrite';
     procedure StringTFDD_Reset (var f : AnyFile; var Buf : ConstAnyString; const s : String); asmname '_p_string_tfdd_reset';
     procedure StringTFDD_Rewrite (var f : AnyFile; var Buf : VarAnyString; var s : String); asmname '_p_string_tfdd_rewrite';
     
     { ========================= FILE HANDLING ROUTINES ======================== }
     
     { Extended pascal binding routines, from bind.c }
     
     const { from types.h }
       Binding_Name_Length = 255;
     
     type
       CFilePtr = Pointer;
     
       UnixTimeType = LongInt; { This is hard-coded in the compiler. Do not change here. }
     
       { The standard fields are Bound and Name. The others are extensions. }
       GPC_BindingType = {@@packed} record
                           Bound             : Boolean;
                           Force             : Boolean;      { Can be set to allow binding to non-writable files or directories }
                           Extensions_Valid  : Boolean;
                           Readable          : Boolean;
                           Writable          : Boolean;
                           Executable        : Boolean;
                           Existing          : Boolean;      { Binding points to an existing file }
                           Directory         : Boolean;      { Binding points to an existing directory; Existing is False then }
                           Size              : LongInt;      { Number of elements or -1 }
                           AccessTime,                       { Time of last access }
                           ModificationTime,                 { Time of last modification }
                           ChangeTime        : UnixTimeType; { Time of last change }
                           Error             : Integer;      { Unused currently }
                           CFile             : CFilePtr;     { allows binding a Pascal file to a C file }
                           Name              : String (Binding_Name_Length)
                         end;
     
     procedure GPC_Bind         (          var aFile : AnyFile; protected var aBinding : BindingType); asmname '_p_bind';
     procedure GetBinding       (protected var aFile : AnyFile;           var aBinding : BindingType); asmname '_p_binding';
     procedure GPC_Unbind       (          var aFile : AnyFile);                                       asmname '_p_unbind';
     procedure ClearBinding     (          var aBinding : BindingType);                                asmname '_p_clearbinding';
     
     { TFDD interface, subject to change! }
     type
       TOpenMode  = (foReset, foRewrite, foAppend, foSeekRead, foSeekWrite, foSeekUpdate);
       TOpenProc  = procedure (var PrivateData; Mode : TOpenMode);
       TReadFunc  = function  (var PrivateData; var   Buffer; Size : SizeType) : SizeType;
       TWriteFunc = function  (var PrivateData; const Buffer; Size : SizeType) : SizeType;
       TFileProc  = procedure (var PrivateData);
       TFlushProc = TFileProc;
       TCloseProc = TFileProc;
       TDoneProc  = TFileProc;
     
     procedure AssignTFDD (var f : AnyFile;
                           OpenProc    : TOpenProc;
                           ReadFunc    : TReadFunc;
                           WriteFunc   : TWriteFunc;
                           FlushProc   : TFlushProc;
                           CloseProc   : TCloseProc;
                           DoneProc    : TDoneProc;
                           PrivateData : Pointer);       asmname '_p_assign_tfdd';
     
     procedure GetTFDD    (var f : AnyFile;
                           var OpenProc    : TOpenProc;
                           var ReadFunc    : TReadFunc;
                           var WriteFunc   : TWriteFunc;
                           var FlushProc   : TFlushProc;
                           var CloseProc   : TCloseProc;
                           var DoneProc    : TDoneProc;
                           var PrivateData : Pointer);   asmname '_p_get_tfdd';
     
     { Default TFDD routines for files. @@ OpenProc and CloseProc still missing. }
     function  F_Read     (var aFile; var   Buffer; Size : SizeType) : SizeType; asmname '_p_f_read';
     function  F_Read_TTY (var aFile; var   Buffer; Size : SizeType) : SizeType; asmname '_p_f_read_tty';
     function  F_Write    (var aFile; const Buffer; Size : SizeType) : SizeType; asmname '_p_f_write';
     procedure F_Flush    (var aFile);                                           asmname '_p_f_flush';
     const     F_Done : (*@@fjf258b*)TDoneProc=TDoneProc (nil);
     
     { bind a filename to an external file, from fassign.pas }
     
     procedure GPC_Assign  (var T : AnyFile; const Name : String); asmname '_p_assign';
     procedure AssignFile  (var T : AnyFile; const Name : String); asmname '_p_assign';
     procedure AssignCFile (var T : AnyFile; CFile : CFilePtr);    asmname '_p_assign_cfile';
     
     { Generic file handling routines and their support, from file.c }
     
     { Flags that can be ORed into FileMode. The default value of FileMode is
       FileMode_Reset_ReadWrite. Sorry for the somewhat confusing values, they
       are meant to be compatible to BP (as far as BP supports this). }
     const
       FileMode_Reset_ReadWrite   = 2; { Allow writing to files opened with Reset }
       FileMode_Rewrite_WriteOnly = 4; { Do not allow reading from files opened with Rewrite }
       FileMode_Extend_WriteOnly  = 8; { Do not allow reading from files opened with Extend }
     
     type
       StatFSBuffer = record
         BlockSize, BlocksTotal, BlocksFree : LongestInt;
         FilesTotal, FilesFree : Integer
       end;
     
     var
       GPC_FileMode : asmname '_p_filemode' Integer;
     
       { Open text files as binary. Only relevant on systems like Dos where
         this makes a difference. }
       TextFilesBinary : asmname '_p_textfiles_binary' Boolean;
     
     procedure GPC_Flush    (          var aFile : AnyFile);                                        asmname '_p_flush';
     function  GPC_GetFile  (protected var aFile : AnyFile) : CFilePtr;                             asmname '_p_getfile';
     
     { Various other versions of Reset, Rewrite and Extend are still overloaded magically }
     procedure GPC_Rewrite  (          var aFile : AnyFile; FileName : CString; Length : Integer);  asmname '_p_rewrite';
     procedure GPC_Extend   (          var aFile : AnyFile; FileName : CString; Length : Integer);  asmname '_p_extend';
     procedure GPC_Reset    (          var aFile : AnyFile; FileName : CString; Length : Integer);  asmname '_p_reset';
     procedure GPC_Close    (          var aFile : AnyFile);                                        asmname '_p_close';
     procedure CloseFile    (          var aFile : (*@@Any*)File);                                        asmname '_p_close';
     function  FileName_CString (protected var aFile : AnyFile) : CString;                          asmname '_p_filename';
     procedure GPC_Erase    (          var aFile : AnyFile);                                        asmname '_p_erase';
     procedure GPC_Rename   (          var aFile : AnyFile; NewName : CString);                     asmname '_p_rename';
     Procedure GPC_ChDir    (Path : CString);                                                       asmname '_p_chdir';
     Procedure GPC_MkDir    (Path : CString);                                                       asmname '_p_mkdir';
     Procedure GPC_RmDir    (Path : CString);                                                       asmname '_p_rmdir';
     procedure GPC_SetFileTime  (      var aFile : AnyFile; Time : UnixTimeType);                   asmname '_p_set_file_time';
     (*@@IO critical*) procedure StatFS       (Path : CString; var Buf : StatFSBuffer);                               asmname '_p_statfs';
     procedure GPC_Get        (var aFile : AnyFile);                    asmname '_p_get';
     function  GPC_EOF        (var aFile : AnyFile) : Boolean;          asmname '_p_eof';
     function  GPC_EOLn       (var aFile : Text)    : Boolean;          asmname '_p_eoln';
     
     { Checks if data are available to be read from aFile. This is similar to
       not EOF (aFile), but does not block on "files" that can grow, like TTYs
       or pipes. }
     function  DataReady      (var aFile : AnyFile) : Boolean;          asmname '_p_data_ready';
     
     { Random access file routines, from randfile.c }
     
     function  GPC_GetSize      (          var aFile : AnyFile) : Integer;           asmname '_p_getsize';
     procedure GPC_Truncate     (          var aFile : AnyFile);                     asmname '_p_truncate';
     procedure GPC_DefineSize   (          var aFile : AnyFile; NewSize :  Integer); asmname '_p_definesize';
     procedure GPC_SeekAll      (          var aFile : AnyFile; NewPlace : Integer); asmname '_p_seekall';
     procedure GPC_SeekRead     (          var aFile : AnyFile; NewPlace : Integer); asmname '_p_seekread';
     procedure GPC_SeekWrite    (          var aFile : AnyFile; NewPlace : Integer); asmname '_p_seekwrite';
     procedure GPC_SeekUpdate   (          var aFile : AnyFile; NewPlace : Integer); asmname '_p_seekupdate';
     function  GPC_Empty        (protected var aFile : AnyFile) : Boolean;           asmname '_p_empty';
     procedure GPC_Update       (          var aFile : AnyFile);                     asmname '_p_update';
     function  GPC_LastPosition (          var aFile : AnyFile) : Integer;           asmname '_p_lastposition';
     function  GPC_Position     (          var aFile : AnyFile) : Integer;           asmname '_p_position';
     
     { Versions with only 3 parameters are still overloaded magically }
     (*@@*)procedure GPC_BlockRead  (var aFile : File;           var Buf : Void; Count : Cardinal; var Result : Cardinal); asmname '_p_blockread';
     (*@@*)procedure GPC_BlockWrite (var aFile : File; protected var Buf : Void; Count : Cardinal; var Result : Cardinal); asmname '_p_blockwrite';
     
     { Routines to output various things, from write.c }
     
     procedure GPC_Page      (var aFile : Text);                       asmname '_p_page';
     procedure GPC_Put       (var aFile : AnyFile);                    asmname '_p_put';
     
     { File name routines, from filename.pas }
     
     {
       Define constants for different systems:
     
       OSDosFlag:         flag to indicate whether the target system is Dos
     
       PathSeparator:     the separator of multiple paths, e.g. in the PATH
                          environment variable
     
       DirSeparator:      the separator of the directories within a full file name
     
       DirSeparators:     a set of all possible directory and drive name separators
     
       ExtSeparator:      the separator of a file name extension
     
       DirSelf:           the name of a directory in itself
     
       DirParent:         the name of the parent directory
     
       NullDeviceName:    the full file name of the null device
     
       TTYDeviceName:     the full file name of the current TTY
     
       ConsoleDeviceName: the full file name of the system console. On Dos systems,
                          this is the same as the TTY, but on systems that allow
                          remote login, this is a different thing and may reach a
                          completely different user than the one running the
                          program, so use with care.
     
       PathEnvVar:        the name of the environment variable which (usually)
                          contains the executable search path
     
       ShellEnvVar:       the name of the environment variable which (usually)
                          contains the path of the shell executable
     
       ConfigFileMask:    a mask for the option file name as returned by
                          ConfigFileName
     }
     
     {$ifdef __OS_DOS__}
     
     const
       OSDosFlag         = True;
       PathSeparator     = ';';
       DirSeparator      = '\';
       DirSeparators     = [':', '\', '/'];
       ExtSeparator      = '.';
       DirSelf           = '.';
       DirParent         = '..';
       NullDeviceName    = 'nul';
       TTYDeviceName     = 'con';
       ConsoleDeviceName = 'con';
       PathEnvVar        = 'PATH';
       ShellEnvVar       = 'COMSPEC';
       ConfigFileMask    = '*.cfg';
     
     {$else}
     
     const
       OSDosFlag         = False;
       PathSeparator     = ':';
       DirSeparator      = '/';
       DirSeparators     = ['/'];
       ExtSeparator      = '.';
       DirSelf           = '.';
       DirParent         = '..';
       NullDeviceName    = '/dev/null';
       TTYDeviceName     = '/dev/tty';
       ConsoleDeviceName = '/dev/console';
       PathEnvVar        = 'PATH';
       ShellEnvVar       = 'SHELL';
       ConfigFileMask    = '.*';
     
     {$endif}
     
     const
       NewLine = {$char-escapes} "\n" {$no-char-escapes}; { the separator of lines within a file }
       WildCardChars = ['*', '?', '[', ']'];
     
     type
       DirPtr = Pointer;
     
       GlobBuffer = record
         Count    : Integer;
         Result   : PCStrings;
         Internal : Pointer
       end;
     
     { libc system call }
     function  CSystem (CmdLine : CString) : Integer;                           asmname 'system';
     
     { Like CSystem, but reports execution errors via the IOResult mechanism,
       returns only the exit status of the executed program. }
     (*@@IO critical*)function  Execute (CmdLine : CString) : Integer;                           asmname '_p_execute';
     
     { Get an environment variable. If it does not exist, GetEnv returns the
       empty string, which can't be distinguished from a variable with an empty
       value, while CGetEnv returns nil then. }
     function  GetEnv  (const EnvVar : String) : TString;                       asmname '_p_getenv';
     function  CGetEnv (EnvVar : CString) : CString;                            asmname 'getenv';
     
     { If s is of the form var=value, the environment variable with the name var
       is set to value. A previous value, if any, is overwritten. The function
       returns 0 on success, and something else otherwise. NOTE: s is NOT copied
       automatically, so unless it's a constant, a copy of the actual variable
       made with StrDup/StrNew should be passed to this function. }
     function  PutEnv  (s : CString) : Integer;                                 asmname 'putenv';
     
     { Change a file name to use the OS dependent directory separator }
     function  Slash2OSDirSeparator (const s : String) : TString;               asmname '_p_slash2osdirseparator';
     
     { Change a file name to use '/' as directory separator }
     function  OSDirSeparator2Slash (const s : String) : TString;               asmname '_p_osdirseparator2slash';
     
     { Like Slash2OSDirSeparator for CStrings -- NOTE: overwrites the CString }
     function  Slash2OSDirSeparator_CString (s : CString) : CString;            asmname '_p_slash2osdirseparator_cstring';
     
     { Like OSDirSeparator2Slash for CStrings -- NOTE: overwrites the CString }
     function  OSDirSeparator2Slash_CString (s : CString) : CString;            asmname '_p_osdirseparator2slash_cstring';
     
     { Add a DirSeparator to the end of s, if there is not already one and
       s denotes an existing directory }
     function  AddDirSeparator (const s : String) : TString;                    asmname '_p_adddirseparator';
     
     { Remove a DirSeparator at the end of s, if there is one }
     function  RemoveDirSeparator (const s : String) : TString;                 asmname '_p_removedirseparator';
     
     { Returns the current directory using OS dependent directory separators }
     function  GetCurrentDirectory     : TString;                               asmname '_p_get_current_directory';
     
     { Returns a directory suitable for storing temporary files using OS dependent
       directory separators. If found, the result always ends in DirSeparator.
       If no directory is found, an empty string is returned. }
     function  GetTempDirectory        : TString;                               asmname '_p_get_temp_directory';
     
     { Returns a non-existing file name in GetTempDirectory. If no temp
       directory is found, i.e. GetTempDirectory returns the empty string,
       a runtime error is raised. }
     function  GetTempFileName         : TString;                               asmname '_p_get_temp_file_name';
     
     { The same as GetTempFileName, but returns a CString allocated from the heap. }
     function  GetTempFileName_CString : CString;                               asmname '_p_get_temp_file_name_cstring';
     
     { Get the external file name }
     function  FileName (var f : AnyFile) : TString;                            asmname '_p_file_name';
     
     { Returns true if the given file name is an existing file }
     function  FileExists      (const FileName : String) : Boolean;             asmname '_p_file_exists';
     
     { Returns true if the given file name is an existing directory }
     function  DirectoryExists (const FileName : String) : Boolean;             asmname '_p_directory_exists';
     
     { If a file of the given name exists in one of the directories given in
       DirList (separated by PathSeparator), returns the full path, otherwise
       returns an empty string. If FileName already contains an element of
       DirSeparators, returns Slash2OSDirSeparator (FileName) if it exists. }
     function  FSearch (const FileName, DirList : String) : TString;            asmname '_p_fsearch';
     
     { Like FSearch, but only find executable files. Under Dos, if not found,
       the function tries appending '.com', '.exe' and '.bat', so you don't have
       to specify these extensions in FileName (and with respect to portability,
       it might be preferable to not do so). }
     function  FSearchExecutable (const FileName, DirList : String) : TString;  asmname '_p_fsearch_executable';
     
     { Replaces all occurrences of `$FOO' and `~' in s by the value of the
       environment variables FOO or HOME, respectively. If a variable is not
       defined, the function returns False, and s contains the name of the
       undefined variable. Otherwise, if all variables are found, s contains
       the replaced string, and True is returned. }
     function  ExpandEnvironment (var s : String) : Boolean;                    asmname '_p_expand_environment';
     
     { Expands the given path name to a full path name. Relative paths are
       expanded using the current directory, and occurrences of DirSelf and
       DirParent are removed. Under Dos, it removes a trailing ExtSeparator
       (except in a trailing DirSelf or DirParent), like Dos does.
       If the directory, i.e. the path without the file name, is invalid,
       the empty string is returned. }
     function  FExpand (const Path : String) : TString;                         asmname '_p_fexpand';
     
     { FExpands Path, and then removes the current directory from it, if it
       is a prefix of it. If OnlyCurDir is set, the current directory will
       be removed only if Path denotes a file in, not below, it. }
     function  RelativePath (const Path : String; OnlyCurDir : Boolean) : TString; asmname '_p_relative_path';
     
     { Is s a UNC filename? (Dos only, otherwise always returns False) }
     function  isUNC (const s : String) : Boolean;                              asmname '_p_isunc';
     
     { Splits a file name into directory, name and extension }
     procedure FSplit (const Path : String; var Dir, Name, Ext : String);       asmname '_p_fsplit';
     
     { Functions that extract one of the parts from FSplit }
     function  DirFromPath  (const Path : String) : TString;                    asmname '_p_dir_from_path';
     function  NameFromPath (const Path : String) : TString;                    asmname '_p_name_from_path';
     function  ExtFromPath  (const Path : String) : TString;                    asmname '_p_ext_from_path';
     
     { Start reading a directory. If successful, a pointer is returned that can
       be used for subsequent calls to ReadDir and finally CloseDir. On failure,
       nil is returned. }
     function  OpenDir  (Name : CString) : DirPtr;                              C;
     
     { Reads one entry from the directory Dir, and returns the file name. On
       errors or end of directory, the empty string is returned. }
     function  ReadDir  (Dir : DirPtr) : TString;                               asmname '_p_readdir';
     
     { Closes a directory opened with OpenDir. Returns 0 on success, anything
       else on error. }
     function  CloseDir (Dir : DirPtr) : Integer;                               asmname '_p_closedir';
     
     { Tests if a file name matches a shell wildcard pattern (?, *, []) }
     function  FileNameMatch (const Pattern, Name : String) : Boolean;          asmname '_p_filenamematch';
     
     { File name globbing }
     procedure Glob     (var Buf : GlobBuffer; Pattern : CString);              asmname '_p_glob';
     procedure GlobFree (var Buf : GlobBuffer);                                 asmname '_p_globfree';
     
     { Return a file name suited for a configuration file.
       Under Unix, it is made up of '$HOME/.' plus the base name (without
       directory) of the running program (as returned by ParamStr (0)) plus 'rc',
       if Global is False (this is meant for user-specific configuration),
       and of '/etc/' plus base name plus 'rc' if Global is True (system-wide
       configuration).
       Under Dos, it is composed of the directory and base name of the running
       program plus '.cfg', regardless of Global.
       If Name is not empty, it will be used instead of the base name of the
       running program. }
     function  ConfigFileName (Name : String; Global : Boolean) : TString;      asmname '_p_config_file_name';
     
     { ========================= MATHEMATICAL ROUTINES ========================= }
     
     const
       Pi = 3.14159265358979323846264338327950288419716;
     
     { Int and Frac routines for real numbers, from math.pas }
     
     function GPC_Frac (x : LongestReal) : LongestReal; asmname '_p_frac';
     function GPC_Int  (x : LongestReal) : LongestReal; asmname '_p_int';
     
     { Transcendental functions for Reals and LongReals, from maths.c }
     
     function Real_Arctan     (x : Double)                : Double;   asmname '_p_arctan';
     function Arctan2         (y, x : Double)             : Double;   asmname '_p_arctan2';
     function Real_Sqrt       (x : Double)                : Double;   asmname '_p_sqrt';
     function Real_Ln         (x : Double)                : Double;   asmname '_p_ln';
     function Real_Exp        (x : Double)                : Double;   asmname '_p_exp';
     function Real_Sin        (x : Double)                : Double;   asmname '_p_sin';
     function SinH            (x : Double)                : Double;   asmname '_p_sinh';
     function Real_Cos        (x : Double)                : Double;   asmname '_p_cos';
     function CosH            (x : Double)                : Double;   asmname '_p_cosh';
     function LongReal_Arctan (x : LongReal)              : LongReal; asmname '_pp_arctan';
     function LongReal_Sqrt   (x : LongReal)              : LongReal; asmname '_pp_sqrt';
     function LongReal_Ln     (x : LongReal)              : LongReal; asmname '_pp_ln';
     function LongReal_Exp    (x : LongReal)              : LongReal; asmname '_pp_exp';
     function LongReal_Sin    (x : LongReal)              : LongReal; asmname '_pp_sin';
     function LongReal_Cos    (x : LongReal)              : LongReal; asmname '_pp_cos';
     
     { Extended Pascal `**' operator }
     function Real_Power      (x, y : Double)             : Double;   asmname '_p_expon';
     function LongReal_Power  (x, y : LongReal)           : LongReal; asmname '_pp_expon';
     
     { from math.pas }
     
     function Real_Pow        (x : Double; y : Integer)   : Double;   asmname '_p_pow';
     function LongReal_Pow    (x : LongReal; y : Integer) : LongReal; asmname '_pp_pow';
     
     { Library functions for complex type arguments, from math.pas }
     
     function Complex_Polar  (Length, Theta : Double)   : Complex; asmname '_p_polar';
     function Complex_Arg    (z : Complex)              : Double;  asmname '_p_arg';
     function Complex_Arctan (z : Complex)              : Complex; asmname '_p_z_arctan';
     function Complex_Sqrt   (z : Complex)              : Complex; asmname '_p_z_sqrt';
     function Complex_Ln     (z : Complex)              : Complex; asmname '_p_z_ln';
     function Complex_Exp    (z : Complex)              : Complex; asmname '_p_z_exp';
     function Complex_Sin    (z : Complex)              : Complex; asmname '_p_z_sin';
     function Complex_Cos    (z : Complex)              : Complex; asmname '_p_z_cos';
     function Complex_Pow    (z : Complex; y : Integer) : Complex; asmname '_p_z_pow';
     function Complex_Power  (z : Complex; y : Double)  : Complex; asmname '_p_z_expon';
     
     { Random number routines, from random.c }
     
     { RandomizePtr, RandRealPtr and RandIntPtr point to these routines by default }
     procedure Default_Randomize;                                 asmname '_p_default_randomize';
     function  Default_RandReal : LongestReal;                    asmname '_p_default_randreal';
     function  Default_RandInt (Max : LongestCard) : LongestCard; asmname '_p_default_randint';
     
     { GPC_Randomize, GPC_RandReal and GPC_RandInt call the actual routines through RandomizePtr, RandRealPtr and RandIntPtr }
     procedure GPC_Randomize;                                 asmname '_p_randomize';
     function  GPC_RandReal : LongestReal;                    asmname '_p_randreal';
     function  GPC_RandInt (Max : LongestCard) : LongestCard; asmname '_p_randint';
     
     type
       RandomizeType = ^procedure;
       RandRealType  = ^function : LongestReal;
       RandIntType   = ^function (Max : LongestCard) : LongestCard;
     
     var
       RandomizePtr : asmname '_p_randomize_ptr' RandomizeType;
       RandRealPtr  : asmname '_p_randreal_ptr'  RandRealType;
       RandIntPtr   : asmname '_p_randint_ptr'   RandIntType;
     
     { ================== OPERATIONS ON CERTAIN BUILT-IN TYPES ================= }
     
     { Time and date routines for Extended Pascal, from times.c }
     
     procedure UnixTimeToTime      (UnixTime : UnixTimeType; var Year, Month, Day, Hour, Minute, Second : Integer); asmname '_p_unix_time_to_time';
     function  TimeToUnixTime      (Year, Month, Day, Hour, Minute, Second : Integer) : UnixTimeType;               asmname '_p_time_to_unix_time';
     function  GetUnixTime         (var MicroSecond : Integer) : UnixTimeType;                                         asmname '_p_get_unix_time';
     
     { Time and date routines for Extended Pascal, from time.pas }
     
     const { from types.h }
       GPC_Date_Length = 11;
       GPC_Time_Length = 8;
     
       MonthName : array [1 .. 12] of String [9] =
         ('January', 'February', 'March', 'April', 'May', 'June',
          'July', 'August', 'September', 'October', 'November', 'December');
     
       MonthLength : array [1 .. 12] of Integer =
         (31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31);
     
     type
       GPC_Date_String = packed array [1 .. GPC_Date_Length] of Char;
       GPC_Time_String = packed array [1 .. GPC_Time_Length] of Char;
     
       GPC_TimeStamp = {@@packed} record
                         DateValid,
                         TimeValid   : Boolean;
                         Year        : Integer;
                         Month       : 1 .. 12;
                         Day         : 1 .. 31;
                         DayOfWeek   : 0 .. 6;  { 0 means Sunday }
                         Hour        : 0 .. 23;
                         Minute      : 0 .. 59;
                         Second      : 0 .. 59;
                         MicroSecond : 0 .. 999999
                       end;
     
     function  GetDayOfWeek        (Day, Month, Year : Integer) : Integer;                                          asmname '_p_dayofweek';
     procedure UnixTimeToTimeStamp (UnixTime : UnixTimeType; var aTimeStamp : TimeStamp);                           asmname '_p_unix_time_to_time_stamp';
     function  TimeStampToUnixTime (protected var aTimeStamp : TimeStamp) : UnixTimeType;                           asmname '_p_time_stamp_to_unix_time';
     procedure GPC_GetTimeStamp    (var aTimeStamp : TimeStamp);                                                    asmname '_p_gettimestamp';
     
     { Is the year a leap year? }
     function  IsLeapYear (Year : Integer) : Boolean; asmname '_p_is_leap_year';
     
     procedure GPC_Date (protected var aTimeStamp : TimeStamp; var Result : GPC_Date_String); asmname '_p_date';
     procedure GPC_Time (protected var aTimeStamp : TimeStamp; var Result : GPC_Time_String); asmname '_p_time';
     
     implementation
     
     end.


File: gpc.info,  Node: Reference,  Next: GPC source,  Prev: Programming,  Up: Top

The Alphabetical GPC Language Reference
***************************************

   *This chapter is under development, so don't be too excited about the
paragraph below!*

   This chapter contains an alphabetical list of all built-in
identifiers of the GNU Pascal compiler.  It does not cover extensions
provided by external libraries which are supposed to come with their
own documentation.

* Menu:

* abs::
* absolute::
* addr::
* AlignOf::
* all::
* and::
* and then::
* and_then::
* AnsiChar::
* append::
* arctan::
* arg::
* array::
* asm::
* asmname::
* Assign::
* assigned::
* attribute::
* begin::
* Bind::
* bindable::
* Binding::
* BindingType::
* BitSizeOf::
* BlockRead::
* BlockWrite::
* Boolean::
* break::
* Byte::
* ByteBool::
* ByteCard::
* ByteInt::
* C::
* C_Language::
* Card::
* Cardinal::
* case::
* Char::
* ChDir::
* chr::
* close::
* cmplx::
* Comp::
* Complex::
* Concat::
* conjugate::
* Const::
* Constructor::
* continue::
* Copy::
* cos::
* CString::
* CString2String::
* Date::
* dec::
* default::
* DefineSize::
* Delete::
* Destructor::
* Dispose::
* div::
* do::
* Double::
* downto::
* else::
* empty::
* end::
* eof::
* eoln::
* EpsReal::
* eq::
* erase::
* Exit::
* exp::
* Export::
* extend::
* Extended::
* extern::
* external::
* false::
* far::
* File::
* FileMode::
* FilePos::
* FileSize::
* FillChar::
* flush::
* for::
* forward::
* frac::
* FreeMem::
* Function::
* ge::
* Get::
* GetFile::
* GetMem::
* GetTimeStamp::
* goto::
* gt::
* Halt::
* high::
* if::
* Im::
* import::
* Implementation::
* in::
* inc::
* Index::
* inherited::
* inline::
* InOutRes::
* InOutResStr::
* Input::
* Insert::
* int::
* Integer::
* Interface::
* IOresult::
* Label::
* LastPosition::
* le::
* length::
* ln::
* LoCase::
* LongCard::
* LongInt::
* LongestCard::
* LongestInt::
* LongestReal::
* LongestWord::
* LongReal::
* LongWord::
* low::
* lt::
* Mark::
* max::
* MaxChar::
* MaxInt::
* MaxReal::
* MedCard::
* MedInt::
* MedReal::
* MedWord::
* min::
* MinReal::
* MkDir::
* mod::
* Module::
* move::
* MoveLeft::
* MoveRight::
* near::
* ne::
* New::
* NewCString::
* Nil::
* not::
* NULL::
* object::
* odd::
* of::
* only::
* Operator::
* or::
* or else::
* or_else::
* ord::
* others::
* otherwise::
* Output::
* pack::
* packed::
* page::
* pAnsiChar::
* ParamCount::
* ParamStr::
* pChar::
* Pointer::
* polar::
* pos::
* Position::
* pow::
* pred::
* Procedure::
* Program::
* protected::
* PtrCard::
* PtrInt::
* PtrWord::
* Put::
* Re::
* read::
* readln::
* ReadStr::
* Real::
* record::
* Release::
* rename::
* repeat::
* reset::
* restricted::
* Result::
* return::
* rewrite::
* RmDir::
* round::
* RunError::
* Seek::
* SeekRead::
* SeekUpdate::
* SeekWrite::
* Self::
* set::
* SetLength::
* SetType::
* ShortCard::
* ShortInt::
* ShortReal::
* ShortWord::
* Single::
* shl::
* shr::
* sin::
* SizeOf::
* SmallInt::
* sqr::
* sqrt::
* StandardError::
* StandardInput::
* StandardOutput::
* static::
* StdErr::
* Str::
* StrPCopy::
* String::
* String2CString::
* SubStr::
* succ::
* Text::
* then::
* Time::
* TimeStamp::
* to::
* to begin::
* to end::
* Trim::
* true::
* trunc::
* Truncate::
* Type::
* TypeOf::
* UnBind::
* Unit::
* unpack::
* until::
* UpCase::
* update::
* uses::
* Val::
* value::
* Var::
* virtual::
* Void::
* while::
* with::
* Word::
* write::
* writeln::
* WriteStr::
* xor::


File: gpc.info,  Node: abs,  Next: absolute,  Up: Reference

abs
===

Syntax
------

       Function abs ( i: INTEGER TYPE ): INTEGER TYPE;
   or
       Function abs ( x: REAL TYPE ): REAL TYPE;
   or
       Function abs ( z: COMPLEX TYPE ): REAL TYPE;

Description
-----------

   Returns the absolute value of the argument.  For integer or real
values of `x', the definition is

       Function abs ( x: INTEGER OR REAL TYPE ): INTEGER OR REAL TYPE;
     
       begin (* abs *)
         if x < 0 then
           abs:= -x
         else
           abs:= x;
       end (* abs *);

   whereas for complex values it is

       Function abs ( x: Complex ): Complex;
     
       begin (* abs *)
         abs:= sqrt ( x * conjugate ( x ) );
       end (* abs *);

Standards
---------

   The function `abs' is defined in ISO-7185 Standard Pascal; its
application to complex values is defined in ISO-10206 Extended Pascal.

Example
-------

       Program TestAbs;
     
       Var
         i1: Complex;
     
       begin
         writeln ( abs ( 42 ) );             (* 42    *);
         writeln ( abs ( -42 ) );            (* 42    *);
         writeln ( abs ( -12.1 ) : 0 : 1 );  (* 12.1  *);
         i1:= cmplx ( 1, 1 );                (* 1 + i *)
         writeln ( abs ( i1 ) : 0 : 3 );     (* 1.414, i.e. sqrt ( 2 ) *)
       end.

See also
--------

   *Note sqr::.


File: gpc.info,  Node: absolute,  Next: addr,  Prev: abs,  Up: Reference

absolute
========

Syntax
------

       Var
         VARIABLE NAME: DATA TYPE absolute VARIABLE REFERENCE;
   or
       Var
         VARIABLE NAME: DATA TYPE absolute INTEGER EXPRESSION;

Description
-----------

   The first meaning of the `absolute' directive allows to put a
variable to the address of another one and thus provides a type-casting
mechanism.

   In most cases, VARIABLE REFERENCE will be just a variable name, but
GPC also allows arbitrary expressions here.  If VARIABLE REFERENCE has
neither a constant address nor is a variable parameter, GPC prints a
warning.  This warning is suppressed in "extended syntax" mode which is
switched on by the `--extended-syntax' option or the `(*$X+*)' compiler
directive.

   Other type-casting mechanisms in GPC are variant records (which are
valid in ISO-7185 Standard Pascal) and explicit type casts.

   The second meaning of `absolute' places a variable at a specified
address.  This is useful on machines without virtual memory addressing
for doing certain low-level operations, but should be avoided on
systems with memory protection such as UNIX-like systems.  GPC does not
check whether the specified virtual address makes any sense and does
not provide a built-in mechanism to map it to a real address.

   GPC warns about this second use of `absolute' unless "extended
syntax" has been requested.

Standards
---------

   ISO Pascal does not define `absolute'.

   Borland Pascal does define `absolute' but has a slightly different
syntax for the second meaning related to the addressing scheme of Intel
X86 processors working in real mode.

   Allowing arbitrary memory references instead of just variable names
in the first meaning of `absolute' is a GNU extension.

Example
-------

       Program TestAbsolute;
     
       (*$X+*)
     
       Const
         IOmemory = $F0000000;
     
       Var
         Mem: array [ 0..MaxInt ] of Byte absolute 0;
         SomeIOport: Byte absolute IOmemory + $C030;
     
       (* Beware:  Using any of the variables above will crash    *)
       (* your program unless you know exactly what you do!       *)
       (* That's why GPC warns about it without the X+ directive. *)
     
       Var
         x: Real;
         a: array [ 1..SizeOf ( Real ) ] of Byte absolute x;
         i: Integer;
     
         b: Byte absolute a [ i ];
         (* GNU extension: non-constant memory reference. *)
     
       begin
         x:= 3.14;
         (* Gather at the internal representation of a real variable. *)
         for i:= 1 to SizeOf ( Real ) do
           write ( a [ i ] : 4 );   (* Or (kind of abuse): `write ( b );' *)
         writeln;
       end.

See also
--------

   *Note record::, *Note Type casts::.


File: gpc.info,  Node: addr,  Next: AlignOf,  Prev: absolute,  Up: Reference

addr
====

   (Under construction.)

Syntax
------

       Function addr ( Const Foo ): Pointer;

Description
-----------

   `addr' returns the address of its argument.

Standards
---------

   `assigned' is a Borland Pascal extension.

Example
-------

See also
--------


File: gpc.info,  Node: AlignOf,  Next: all,  Prev: addr,  Up: Reference

AlignOf
=======

Syntax
------

       Function AlignOf ( Var x ): Integer;

Description
-----------

   Returns the alignment of a type or variable in bytes.

Standards
---------

   `AlignOf' is a GNU extension.

Example
-------

       Var
         a: Integer;
         b: array [ 1..8 ] of Char;
     
       ...
     
       writeln ( AlignOf ( a ) );  (* Alignment of `Integer'; usually 4 bytes. *)
       writeln ( AlignOf ( b ) );  (* Alignment of `Char'; usually 1 byte. *)

   Although the array is bigger than a single char, it is accessed char
by char, so there usually is no need to align it on a 4 byte boundary
or such.  (This may be false on some platforms.)

See also
--------

   *Note SizeOf::, *Note BitSizeOf::, *Note TypeOf::.


File: gpc.info,  Node: all,  Next: and,  Prev: AlignOf,  Up: Reference

all
===

Description
-----------

   `all' is a predefined export interface for Extended Pascal modules.
You can use it to export all identifiers declared in an interface module
automatically.

Standards
---------

   `all' is a GNU extension.

Example
-------

       Module TestAll Interface;
     
       export
         foo = all;  (* Same as `foo = ( a, b, bar );' *)
     
       Var
         a, b: Integer;
     
       Procedure bar;
     
       end.

See also
--------

   *Note Modules::.


File: gpc.info,  Node: and,  Next: and then,  Prev: all,  Up: Reference

and
===

Syntax
------

       Operator and ( operand1, operand2: Boolean ) = result: Boolean;
   or
       Operator and ( operand1, operand2: INTEGER TYPE ) = result: INTEGER TYPE;
   or
       Procedure and ( Var operand1: INTEGER TYPE; operand2: INTEGER TYPE );

Description
-----------

   In GNU Pascal, `and' has three built-in meanings:

  1. Logical "and" between two `Boolean'-type expressions.  The result
     of the operation is of `Boolean' type.

     By default, `and' acts as a short-circuit operator in GPC:  If the
     first operand is `false', the second operand is not evaluated
     because the result is already known to be `false'.  You can change
     this to complete evaluation using the `--no-short-circuit'
     command-line option or the `(*$B+*)' compiler directive.

  2. Bitwise "and" between two integer-type expressions.  The result is
     of the common integer type of both expressions.

  3. Use as a "procedure":  `operand1' is "and"ed bitwise with
     `operand2'; the result is stored in `operand1'.


Standards
---------

   The logical `and' operator is defined in ISO-7185 Standard Pascal.

   According to ISO, you cannot rely on `and' being a short-circuit
operator.  On the other hand, GPC's default behaviour does *not*
contradict the ISO standard.  (See *Note and_then::.)  However, since
it seems to be a de-facto standard among ISO Pascal compilers to
evaluate both operands of `and', GPC switches to `--no-short-circuit'
mode if one of the language dialect options selecting ISO Pascal, for
instance `--extended-pascal', is given.  Use `--short-circuit' to
override.

   ISO Pascal does not define the bitwise `and' operator; Borland
Pascal and Delphi do.

   Use of `and' as a "procedure" is a GNU extension.

Example
-------

       Var
         a, b, c: Integer;
     
       ...
     
       if ( a = 0 ) and ( b = 0 ) then  (* logical `and' *)
         c:= 1
       else if a and b = 0 then  (* bitwise `and' *)
         c:= 2
       else
         and ( c, a );  (* same as `c:= c and a' *)

   Note the difference between the logical `and' and the bitwise `and':
When `a' is 2 and `b' is 4, then `a and b' is 0.  *Beware:*  `a and b
= 0' has nothing to do with `( a = 0 ) and ( b = 0 )'!

   Since bitwise `and' has a higher priority than the `=' operator,
parentheses are needed in `if ( a = 0 ) and ( b = 0 )' because otherwise
`0 and b' would be calculated first, and the remainder would cause a
parse error.

See also
--------

   *Note and_then::, *Note and then::, *Note or::, *Note xor::, *Note
Operators::.


File: gpc.info,  Node: and then,  Next: and_then,  Prev: and,  Up: Reference

and then
========

Description
-----------

   `and then' is an alias for the short-circuit logical operator
`and_then'.

Standards
---------

   While `and_then' is defined in ISO-10206 Extended Pascal, `and then'
is a GNU Extension.

Example
-------

       Var
         p: ^Integer;
     
       [...]
     
       if ( p <> Nil ) and then ( p^ < 42 ) then  (* This is safe. *)
         [...];

See also
--------

   *Note and_then::, *Note and::, *Note or else::.


File: gpc.info,  Node: and_then,  Next: AnsiChar,  Prev: and then,  Up: Reference

and_then
========

Syntax
------

       Operator and_then ( operand1, operand2: Boolean ) = result: Boolean;

Description
-----------

   The `and_then' short-circuit logical operator performs the same
operation as the logical operator `and'.  But while the ISO standard
does not specify anything about the evaluation of the operands of
`and'--they may be evaluated in any order, or not at all--`and_then'
has a well-defined behaviour:  It evaluates the first operand.  If the
result is `false', `and_then' returns `false' without evaluating the
second operand.  If it is `true', the second operand is evaluated and
returned.

   Since the behaviour described above is the most effective way to
implement `and', GPC by default treats `and' and `and_then' exactly the
same.  If you want, for some reason, to have both operands of `and'
evaluated completely, you can specify the `--no-short-circuit'
command-line option, but this is not portable.  The portable way to
have both operands evaluated is to assign both to temporary variables
and then use `and'--or `and_then', it does not matter.

Standards
---------

   ISO-7185 Standard Pascal does not define `and_then'; ISO-10206
Extended Pascal does.

   Some people think that the ISO standard requires both operands of
`and' to be evaluated.  This is false.  What the ISO standard *does*
say is that you cannot rely on a certain order of evaluation of the
operands of `and'; in particular things like

       Var
         p: ^Integer;
     
       [...]
     
       if ( p <> Nil ) and ( p^ < 42 ) then
         [...];

can crash according to ISO Pascal, although they cannot crash when
compiled with GNU Pascal running in default mode.

   If you want to write portable and efficient code in ISO-10206
Extended Pascal, *always* use `and_then'; *never* use `and'.

Example
-------

       Var
         p: ^Integer;
     
       [...]
     
       if ( p <> Nil ) and_then ( p^ < 42 ) then  (* This is safe. *)
         [...];

See also
--------

   *Note and then::, *Note and::, *Note or_else::.


File: gpc.info,  Node: AnsiChar,  Next: append,  Prev: and_then,  Up: Reference

AnsiChar
========

Syntax
------

       Type
         AnsiChar = Char;

Description
-----------

   `AnsiChar' is an 8 bit char type.  Currently, it is the same as
`Char', but this might change in the future, once `wide chars' (16 bit
chars) will be introduced into GPC.  Depending on the platform, `Char'
might be either `AnsiChar' or `WideChar' then.

Standards
---------

   ISO Pascal does not define `AnsiChar'; Delphi does.

Example
-------

       Var
         A: AnsiChar;  (* There is nothing special with `AnsiChar'. *)
         B: Char;
     
       [...]
     
       A:= 'A';
       A:= B;

See also
--------

   *Note pAnsiChar::, *Note Char::.


File: gpc.info,  Node: append,  Next: arctan,  Prev: AnsiChar,  Up: Reference

append
======

Syntax
------

       Procedure append ( Var F: ANY FILE );

Description
-----------

Standards
---------

   `append' is a Borland Pascal extension.  ISO-10206 Extended Pascal
has *Note extend:: instead.

Example
-------

See also
--------

   *Note Assign::, *Note reset::, *Note rewrite::, *Note update::,
*Note extend::.


File: gpc.info,  Node: arctan,  Next: arg,  Prev: append,  Up: Reference

arctan
======

Syntax
------

       Function arctan ( x: Real ): Real;
   or
       Function arctan ( z: Complex ): Complex;

Description
-----------

   `arctan' returns the (principal value of the) arcus tangent of the
argument.  The result is in the range `-pi / 2 < arctan ( x ) < pi / 2'
for real arguments.

Standards
---------

   The function `arctan' is defined in ISO-7185 Standard Pascal; its
application to complex values is defined in ISO-10206 Extended Pascal.

Example
-------

       writeln ( 4 * arctan ( 1 ) : 0 : 5 );
       (* yields 3.14159; arctan ( 1 ) = pi / 4. *)

See also
--------

   *Note sin::, *Note cos::, *Note ln::, *Note arg::.


File: gpc.info,  Node: arg,  Next: array,  Prev: arctan,  Up: Reference

arg
===

Syntax
------

       Function arg ( z: Complex ): Real;

Description
-----------

   `arg' returns the complex "argument", i.e. the angle (in radian) in
the complex plane with respect to the real axis, of its parameter `z'.
The result is in the range of `-pi < arg ( z ) <= pi'.

Standards
---------

   ISO-7185 Standard Pascal does not define `arg'; ISO-10206 Extended
Pascal does.

Example
-------

       Program TestArg;
     
       Var
         z: Complex;
     
       begin
         z:= cmplx ( 1, 1 );  (* 1 + i *)
         writeln ( arg ( z ) : 0 : 5 );
         (* yields 0.78540, i.e. pi / 4. *)
       end.

See also
--------

   *Note arctan::, *Note ln::, *Note polar::.


File: gpc.info,  Node: array,  Next: asm,  Prev: arg,  Up: Reference

array
=====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: asm,  Next: asmname,  Prev: array,  Up: Reference

asm
===

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: asmname,  Next: Assign,  Prev: asm,  Up: Reference

asmname
=======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Assign,  Next: assigned,  Prev: asmname,  Up: Reference

Assign
======

Syntax
------

       Procedure Assign ( Var F: ANY FILE; FileName: String );

Description
-----------

Standards
---------

   `Assign' is a Borland Pascal extension.

Example
-------

See also
--------

   *Note reset::, *Note rewrite::, *Note update::, *Note extend::,
*Note append::.


File: gpc.info,  Node: assigned,  Next: attribute,  Prev: Assign,  Up: Reference

assigned
========

   (Under construction.)

Syntax
------

       Function assigned ( p: Pointer ): Boolean;
   or
       Function assigned ( p: PROCEDURAL TYPE ): Boolean;

Description
-----------

Standards
---------

   `assigned' is a Borland Pascal extension.

Example
-------

See also
--------


File: gpc.info,  Node: attribute,  Next: begin,  Prev: assigned,  Up: Reference

attribute
=========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: begin,  Next: Bind,  Prev: attribute,  Up: Reference

begin
=====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Bind,  Next: bindable,  Prev: begin,  Up: Reference

Bind
====

   (Under construction.)

Syntax
------

       Procedure Bind ( Var F: ANY FILE; B: BindingType );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: bindable,  Next: Binding,  Prev: Bind,  Up: Reference

bindable
========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Binding,  Next: BindingType,  Prev: bindable,  Up: Reference

Binding
=======

   (Under construction.)

Syntax
------

       Function Binding ( F: ANY FILE ): BindingType;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: BindingType,  Next: BitSizeOf,  Prev: Binding,  Up: Reference

BindingType
===========

   (Under construction.)

Syntax
------

     UnixTimeType = LongInt;
     
     GPC_BindingType = {@@packed} record
                         Bound             : Boolean;
                         Force             : Boolean;      { Can be set to allow binding to non-writable files or directories }
                         Extensions_Valid  : Boolean;
                         Readable          : Boolean;
                         Writable          : Boolean;
                         Executable        : Boolean;
                         Existing          : Boolean;      { Binding points to an existing file }
                         Directory         : Boolean;      { Binding points to an existing directory; Existing is False then }
                         Size              : LongInt;      { Number of elements or -1 }
                         AccessTime,                       { Time of last access }
                         ModificationTime,                 { Time of last modification }
                         ChangeTime        : UnixTimeType; { Time of last change }
                         Error             : Integer;      { Unused currently }
                         CFile             : CFilePtr;     { allows binding a Pascal file to a C file }
                         Name              : String (Binding_Name_Length)
                       end;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: BitSizeOf,  Next: BlockRead,  Prev: BindingType,  Up: Reference

BitSizeOf
=========

Syntax
------

       Function BitSizeOf ( Var x ): Integer;

Description
-----------

   Returns the size of a type or variable in bits.

Standards
---------

   `BitSizeOf' is a GNU extension.

Example
-------

       Var
         a: Integer;
         b: array [ 1..8 ] of Char;
         c: Integer ( 12 );
     
         d: packed record
           x: Integer ( 12 );
           y: 0..3;
         end (* d *);
     
       ...
     
       writeln ( BitSizeOf ( a ) );  (* Size of an `Integer'; usually 32 bits.  *)
       writeln ( BitSizeOf ( b ) );  (* Size of eight `Char's; usually 64 bits. *)
       writeln ( BitSizeOf ( c ) );  (* 16 bits (smallest addressable space).   *)
     
       writeln ( BitSizeOf ( d ) );    (* 16 *)
       writeln ( BitSizeOf ( d.x ) );  (* 12 *)
       writeln ( BitSizeOf ( d.y ) );  (*  2 *)

See also
--------

   *Note SizeOf::, *Note AlignOf::, *Note TypeOf::.


File: gpc.info,  Node: BlockRead,  Next: BlockWrite,  Prev: BitSizeOf,  Up: Reference

BlockRead
=========

   (Under construction.)

Syntax
------

       Procedure BlockRead ( Var F: File; Var Buffer; Blocks: Integer );
   or
       Procedure BlockRead ( Var F: File; Var Buffer; Blocks: Integer;
                             Var BlocksRead: Integer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: BlockWrite,  Next: Boolean,  Prev: BlockRead,  Up: Reference

BlockWrite
==========

   (Under construction.)

Syntax
------

       Procedure BlockWrite ( Var F: File; Const Buffer; Blocks: Integer );
   or
       Procedure BlockWrite ( Var F: File; Const Buffer; Blocks: Integer;
                              Var BlocksWritten: Integer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Boolean,  Next: break,  Prev: BlockWrite,  Up: Reference

Boolean
=======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: break,  Next: Byte,  Prev: Boolean,  Up: Reference

break
=====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Byte,  Next: ByteBool,  Prev: break,  Up: Reference

Byte
====

Description
-----------

   `Byte' is an unsigned integer type which is one "unit" wide.  On
most platforms one unit has 8 bits, therefore the type is named "byte"
and usually has a range of `0..255'.  (It is the same as *Note
ByteCard::.)

   `Byte' in GNU Pascal is compatible to `unsigned char' in GNU C.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `Byte'.  (However see *Note Subrange
types::.)

   The `Byte' type appears in Borland Pascal and Delphi, too, where it
is an unsigned 8-bit integer type.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: ByteBool,  Next: ByteCard,  Prev: Byte,  Up: Reference

ByteBool
========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: ByteCard,  Next: ByteInt,  Prev: ByteBool,  Up: Reference

ByteCard
========

Description
-----------

   `ByteCard' is an unsigned integer type which is one "unit" wide.  On
most platforms one unit has 8 bits, therefore the type is prefixed
"byte-" and usually has a range of `0..255'.

   `ByteCard' in GNU Pascal is compatible to `unsigned char' in GNU C.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `ByteCard'.  (However see *Note Subrange
types::.)

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: ByteInt,  Next: C,  Prev: ByteCard,  Up: Reference

ByteInt
=======

Description
-----------

   `ByteInt' is a signed integer type which is one "unit" wide.  On
most platforms one unit has 8 bits, therefore the type is prefixed
"byte-" and usually has a range of `-128..127'.

   `ByteInt' in GNU Pascal is compatible to `signed char' in GNU C.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `ShortInt'.  (However see *Note Subrange
types::.)

   `ByteInt' in GNU Pascal corresponds to *Note ShortInt:: in Borland
Pascal and Delphi.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: C,  Next: C_Language,  Prev: ByteInt,  Up: Reference

C
=

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: C_Language,  Next: Card,  Prev: C,  Up: Reference

C_Language
==========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Card,  Next: Cardinal,  Prev: C_Language,  Up: Reference

Card
====

   (Under construction.)

Syntax
------

       Function Card ( S: ANY SET ): Integer;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Cardinal,  Next: case,  Prev: Card,  Up: Reference

Cardinal
========

Description
-----------

   `Cardinal' is the "natural" unsigned integer type in GNU Pascal.  On
most platforms it is 32 bits wide and thus has a range of
`0..4294967295'.  Use it whenever you need a general-purpose unsigned
integer type and don't need to care about compatibility to other Pascal
dialects.

   As an extension, GPC allows to use `Cardinal' as a pseudo-schema to
produce types with a specified size in bits; for example

       Type
         Card16 = Cardinal ( 16 );

   defines an unsigned integer type with 16 bits.  The same mechanism
works for `Integer' and `Word', too.

   `Cardinal' in GNU Pascal is compatible to `unsigned int' in GNU C.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `Cardinal'.  (However see *Note Subrange
types::.)

   The `Cardinal' type appears in Delphi, too, where it has 16 bits in
version 1.0, 32 from version 2.0 on.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: case,  Next: Char,  Prev: Cardinal,  Up: Reference

case
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Char,  Next: ChDir,  Prev: case,  Up: Reference

Char
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: ChDir,  Next: chr,  Prev: Char,  Up: Reference

ChDir
=====

   (Under construction.)

Syntax
------

       Procedure ChDir ( Directory: String );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: chr,  Next: close,  Prev: ChDir,  Up: Reference

chr
===

   (Under construction.)

Syntax
------

       Function chr ( AsciiCode: Integer ): Char;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: close,  Next: cmplx,  Prev: chr,  Up: Reference

close
=====

   (Under construction.)

Syntax
------

       Procedure Close ( Var F: ANY FILE );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: cmplx,  Next: Comp,  Prev: close,  Up: Reference

cmplx
=====

   (Under construction.)

Syntax
------

       Function cmplx ( RealPart, ImaginaryPart: Real ): Complex;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Comp,  Next: Complex,  Prev: cmplx,  Up: Reference

Comp
====

Description
-----------

   `Comp' is a signed integer type which is longer than `Integer'.  On
most platforms it is 64 bits wide and thus has a range of
`-9223372036854775808..9223372036854775807'.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `Comp'.

   Borland Pascal and Delphi also define `Comp' as a 64-bit signed
integer type.  This compatibility is the reason why GPC supports `Comp'.
In some contexts, the Borland compilers treat `Comp' as a "real"
type--this behaviour is not supported by GPC.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: Complex,  Next: Concat,  Prev: Comp,  Up: Reference

Complex
=======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Concat,  Next: conjugate,  Prev: Complex,  Up: Reference

Concat
======

   (Under construction.)

Syntax
------

       Function Concat ( S1, S2: String ): String;
   or
       Function Concat ( S1, S2, S3: String ): String;
   or
       ...

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: conjugate,  Next: Const,  Prev: Concat,  Up: Reference

conjugate
=========

   (Under construction.)

Syntax
------

       Function conjugate ( z: Complex ): Complex;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Const,  Next: Constructor,  Prev: conjugate,  Up: Reference

Const
=====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Constructor,  Next: continue,  Prev: Const,  Up: Reference

Constructor
===========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: continue,  Next: Copy,  Prev: Constructor,  Up: Reference

continue
========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Copy,  Next: cos,  Prev: continue,  Up: Reference

Copy
====

Syntax
------

       Function Copy ( S: String; FirstChar, Count: Integer ): String;
   or
       Function Copy ( S: String; FirstChar: Integer ): String;

Description
-----------

   `Copy' returns a sub-string of S starting with the character at
position FIRSTCHAR.  If COUNT is given, such many characters will be
copied into the sub-string.  If COUNT is omitted, the sub-string will
will range to the end of S.

   If `Count' is too large for the sub-string to fit in S, the result
will be truncated at the end of S.  If `FirstChar' exceeds the length
of S, the empty string will be returned.  (For a function which does
not truncate but triggers a runtime error instead, see *Note SubStr::.)

   Please note that GPC's strings may be longer than 255 characters.  If
you want to isolate the second half of a string S starting with the
third character, use `Copy ( S, 3 )' instead of `Copy ( S, 3, 255 )'.

Standards
---------

   `Copy' is defined in UCSD and Borland Pascal.  It does not appear in
ISO Pascal.  The possibility to omit the third parameter is a GPC
extension.

Example
-------

       Var
         S: String ( 42 );
     
       [...]
     
       S:= 'Hello';
       writeln ( Copy ( S, 2, 3 ) );   (* yields "ell" *)
       writeln ( Copy ( S, 3 ) );      (* yields "llo" *)
       writeln ( Copy ( S, 4, 7 ) );   (* yields "lo" *)
       writeln ( Copy ( S, 42 ) );     (* yields the empty string *)

See also
--------

   *Note SubStr::, String slice access.


File: gpc.info,  Node: cos,  Next: CString,  Prev: Copy,  Up: Reference

cos
===

   (Under construction.)

Syntax
------

       Function cos ( x: Real ): Real;
   or
       Function cos ( z: Complex ): Complex;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: CString,  Next: CString2String,  Prev: cos,  Up: Reference

CString
=======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: CString2String,  Next: Date,  Prev: CString,  Up: Reference

CString2String
==============

   (Under construction.)

Syntax
------

       Function CString2String ( S: CString ): String;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Date,  Next: dec,  Prev: CString2String,  Up: Reference

Date
====

   (Under construction.)

Syntax
------

       Function Date ( T: TimeStamp ):
           packed array [ 1..DATE LENGTH ] of Char;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: dec,  Next: default,  Prev: Date,  Up: Reference

dec
===

   (Under construction.)

Syntax
------

       Procedure dec ( Var x: ORDINAL TYPE );
   or
       Procedure dec ( Var x: ORDINAL TYPE; amount: Integer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: default,  Next: DefineSize,  Prev: dec,  Up: Reference

default
=======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: DefineSize,  Next: Delete,  Prev: default,  Up: Reference

DefineSize
==========

   (Under construction.)

Syntax
------

       Procedure DefineSize ( Var F: ANY FILE; NewSize: Integer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Delete,  Next: Destructor,  Prev: DefineSize,  Up: Reference

Delete
======

   (Under construction.)

Syntax
------

       Procedure Delete ( Var S: String; FirstChar, Count: Integer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Destructor,  Next: Dispose,  Prev: Delete,  Up: Reference

Destructor
==========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Dispose,  Next: div,  Prev: Destructor,  Up: Reference

Dispose
=======

   (Under construction.)

Syntax
------

       Dispose ( PointerVar: Pointer );
   or
       Dispose ( PointerVar: Pointer; TAG FIELD VALUES );
   or
       Dispose ( ObjectPointerVar: Pointer; DESTRUCTOR CALL );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: div,  Next: do,  Prev: Dispose,  Up: Reference

div
===

   (Under construction.)

Syntax
------

       Operator div ( p, q: Integer ) = r: Integer;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: do,  Next: Double,  Prev: div,  Up: Reference

do
==

Description
-----------

   The `do' reserved word is used in combination with other Pascal
keywords in many ways. For description and examples see the relevant
reference sections:  `for', `while', `with', `to begin', `to end'.

Standards
---------

   `do' is defined in the ISO-7185 Standard Pascal and supported by all
known Pascal variants.

See also
--------

   *Note for::, *Note while::, *Note with::, *Note to begin::, *Note to
end::.


File: gpc.info,  Node: Double,  Next: downto,  Prev: do,  Up: Reference

Double
======

   (Under construction.)

Syntax
------

       Type
         Double = Real;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: downto,  Next: else,  Prev: Double,  Up: Reference

downto
======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: else,  Next: empty,  Prev: downto,  Up: Reference

else
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: empty,  Next: end,  Prev: else,  Up: Reference

empty
=====

   (Under construction.)

Syntax
------

       Function empty ( Var F: ANY FILE ): Boolean;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: end,  Next: eof,  Prev: empty,  Up: Reference

end
===

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: eof,  Next: eoln,  Prev: end,  Up: Reference

eof
===

   (Under construction.)

Syntax
------

       Function eof ( Var F: ANY FILE ): Boolean;
   or
       Function eof: Boolean;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: eoln,  Next: EpsReal,  Prev: eof,  Up: Reference

eoln
====

   (Under construction.)

Syntax
------

       Function eoln ( Var F: ANY FILE ): Boolean;
   or
       Function eoln: Boolean;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: EpsReal,  Next: eq,  Prev: eoln,  Up: Reference

EpsReal
=======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: eq,  Next: erase,  Prev: EpsReal,  Up: Reference

eq
==

   (Under construction.)

Syntax
------

       Function eq ( S1, S2: String ): Boolean;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: erase,  Next: Exit,  Prev: eq,  Up: Reference

erase
=====

   (Under construction.)

Syntax
------

       Procedure erase ( Var F: ANY FILE );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Exit,  Next: exp,  Prev: erase,  Up: Reference

Exit
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: exp,  Next: Export,  Prev: Exit,  Up: Reference

exp
===

   (Under construction.)

Syntax
------

       Function exp ( x: Real ): Real;
   or
       Function exp ( z: Complex ): Complex;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Export,  Next: extend,  Prev: exp,  Up: Reference

Export
======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: extend,  Next: Extended,  Prev: Export,  Up: Reference

extend
======

   (Under construction.)

Syntax
------

       Procedure extend ( Var F: ANY FILE );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Extended,  Next: extern,  Prev: extend,  Up: Reference

Extended
========

   (Under construction.)

Syntax
------

       Type
         Extended = LongReal;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: extern,  Next: external,  Prev: Extended,  Up: Reference

extern
======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: external,  Next: false,  Prev: extern,  Up: Reference

external
========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: false,  Next: far,  Prev: external,  Up: Reference

false
=====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: far,  Next: File,  Prev: false,  Up: Reference

far
===

Description
-----------

   The `far' directive can be appended to a procedure or function
heading but is ignored by GPC.  It is there for Borland compatibility,
only.  (Since the GNU compilers provide a flat memory model, the
distinction between `near' and `far' pointers is void.)

Standards
---------

   ISO Pascal does not define `far', Borland Pascal does.

Example
-------

       Var
         p: Procedure;
     
       Procedure Foo; far;  (* `far' has no effect in GPC *)
     
       begin (* Foo *)
         [...]
       end (* Foo *);
     
       [...]
     
       p:= Foo;  (* Would also work without `far' in GPC. *)

See also
--------

   *Note near::.


File: gpc.info,  Node: FileMode,  Next: FilePos,  Prev: File,  Up: Reference

FileMode
========

   (Under construction.)

Syntax
------

       Var
         FileMode: Integer;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: File,  Next: FileMode,  Prev: far,  Up: Reference

File
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: FilePos,  Next: FileSize,  Prev: FileMode,  Up: Reference

FilePos
=======

   (Under construction.)

Syntax
------

       Function FilePos ( Var F: ANY FILE ): Integer;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: FileSize,  Next: FillChar,  Prev: FilePos,  Up: Reference

FileSize
========

   (Under construction.)

Syntax
------

       Function FileSize ( Var F: ANY FILE ): Integer;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: FillChar,  Next: flush,  Prev: FileSize,  Up: Reference

FillChar
========

   (Under construction.)

Syntax
------

       Procedure FillChar ( Var Dest; Count: Integer; Value: Char );
   or
       Procedure FillChar ( Var Dest; Count: Integer; Value: Byte );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: flush,  Next: for,  Prev: FillChar,  Up: Reference

flush
=====

   (Under construction.)

Syntax
------

       Procedure flush ( Var F: ANY FILE );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: for,  Next: forward,  Prev: flush,  Up: Reference

for
===

   (Under construction.)

Syntax
------

       for ORDINAL VARIABLE := INITIAL VALUE to FINAL VALUE do
         STATEMENT
   or
       for ORDINAL VARIABLE := INITIAL VALUE downto FINAL VALUE do
         STATEMENT
   or
       for ORDINAL VARIABLE in SOME SET do
         STATEMENT

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: forward,  Next: frac,  Prev: for,  Up: Reference

forward
=======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: frac,  Next: FreeMem,  Prev: forward,  Up: Reference

frac
====

   (Under construction.)

Syntax
------

       Function frac ( x: Real ): Real;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: FreeMem,  Next: Function,  Prev: frac,  Up: Reference

FreeMem
=======

Syntax
------

       Procedure FreeMem ( Var p: Pointer; Size: Cardinal );
   or
       Procedure FreeMem ( Var p: Pointer );

Description
-----------

   Releases a chunk of memory previously allocated using `GetMem'.  The
parameter SIZE is optional, and its value is ignored.

   Since Extended Pascal's schemata provide a cleaner way to implement
dynamical arrays and such, we recommend using `GetMem' and `FreeMem'
only for low-level applications or for interfacing with other languages.

Standards
---------

   ISO Pascal does not define `FreeMem', Borland Pascal does and
requires two parameters.  `FreeMem' with only one parameter is a GNU
extension.

Example
-------

   *Note GetMem::

See also
--------

   *Note GetMem::, *Note Schemata::, *Note Dispose::, *Note Mark::,
*Note Release::.


File: gpc.info,  Node: Function,  Next: ge,  Prev: FreeMem,  Up: Reference

Function
========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: ge,  Next: Get,  Prev: Function,  Up: Reference

ge
==

   (Under construction.)

Syntax
------

       Function ge ( S1, S2: String ): Boolean;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Get,  Next: GetFile,  Prev: ge,  Up: Reference

Get
===

   (Under construction.)

Syntax
------

       Procedure Get ( Var F: TYPED FILE );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: GetFile,  Next: GetMem,  Prev: Get,  Up: Reference

GetFile
=======

Syntax
------

       Function GetFile ( F: FILE TYPE ): Pointer;

Description
-----------

   GNU Pascal files internally contain a C `FILE' descriptor.
`GetFile' returns a pointer to this, so you can pass it to external
procedures or functions, perhaps written in C, that cannot handle
Pascal files.

Standards
---------

   `GetFile' is a GNU extension.

Example
-------

       Program Hello;
     
       Procedure fputs ( S: CString; someFile: Pointer ); C;
     
       begin
         fputs ( 'Hello, world!'^J, GetFile ( Output ) );
       end.

See also
--------

   *Note C::, *Note CString::, *Note Other languages::.


File: gpc.info,  Node: GetMem,  Next: GetTimeStamp,  Prev: GetFile,  Up: Reference

GetMem
======

Syntax
------

       Procedure GetMem ( Var p: Pointeger; Size: Cardinal );
   or
       Function GetMem ( Size: Cardinal ): Pointer;

Description
-----------

   Allocates dynamical storage on the heap and returns a pointer to it
in `p' or as the function result.

   Since Extended Pascal's schemata provide a cleaner way to implement
dynamical arrays and such, we recommend using `GetMem' and `FreeMem'
only for low-level applications.

Standards
---------

   ISO Pascal does not define `GetMem', Borland Pascal does, but only
as a procedure.  `GetMem' as a function is a GNU extension.

Example
-------

   The Borland-comatibility Unit `Graph' from the `BPcompat' package
supports a `GetImage' and a `PutImage' procedure which need a variable
of size `ImageSize' as a buffer.  Since these are "black box" routines,
the buffer can't reasonably be a schema providing a dynamical array.
Instead, we have to use `GetMem' and `FreeMem' for dynamical memory
allocation.

       Program TestGetMem;
     
       uses
         Graph;
     
       Var
         Buffer: Pointer;
         Size: Cardinal;
     
       begin
         [...]
         Size:= ImageSize ( 10, 10, 60, 30 );
         Buffer:= GetMem ( Size );  (* or: GetMem ( Buffer, Size ); *)
         GetImage ( 10, 10, 60, 30, Buffer^ );
         [...]
         FreeMem ( Buffer );  (* or: FreeMem ( Buffer, Size ); *)
         [...]
       end.

See also
--------

   *Note FreeMem::, *Note New::, *Note Schemata::.


File: gpc.info,  Node: GetTimeStamp,  Next: goto,  Prev: GetMem,  Up: Reference

GetTimeStamp
============

   (Under construction.)

Syntax
------

       Procedure GetTimeStamp ( Var T: TimeStamp );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: goto,  Next: gt,  Prev: GetTimeStamp,  Up: Reference

goto
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: gt,  Next: Halt,  Prev: goto,  Up: Reference

gt
==

   (Under construction.)

Syntax
------

       Function gt ( S1, S2: String ): Boolean;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Halt,  Next: high,  Prev: gt,  Up: Reference

Halt
====

   (Under construction.)

Syntax
------

       Procedure Halt;
   or
       Procedure Halt ( ExitCode: Integer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: high,  Next: if,  Prev: Halt,  Up: Reference

high
====

   (Under construction.)

Syntax
------

       Function high ( ORDINAL TYPE OR VARIABLE ): Integer;
   or
       Function high ( ARRAY TYPE OR VARIABLE ): Integer;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: if,  Next: Im,  Prev: high,  Up: Reference

if
==

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Im,  Next: import,  Prev: if,  Up: Reference

Im
==

   (Under construction.)

Syntax
------

       Function Im ( z: Complex ): Real;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: import,  Next: Implementation,  Prev: Im,  Up: Reference

import
======

Description
-----------

   The reserved word `import' in the *import part* of a program makes
the program import an interface.  The syntax is

       Program foo;
     
       import
         bar1;
         bar3 ( baz1 => glork1 ) in 'baz.pas';
         bar2 only ( baz2, baz3 => glork2 );
     
       [...]

   The `in' above tells GPC to look for the `Module' in the specified
file; otherwise the file name is derived from the name of the interface
by adding first `.p', then `.pas'--which only works if the name of the
exported interface coincides with the file name.

   The symbol `=>' denotes import renaming:  The entity which is
exported under the name `baz1' by the interface `bar3' will be known
under the new name `glork1' in the program.

   The `only' qualifier means that only the listed identifiers will be
imported from the interface.  Renaming works together with `only', too.

   There must be at most one import part in a program.

   The interfaces needn't be exported by Extended Pascal Modules but
may be UCSD/Borland Pascal Units as well.

Standards
---------

   ISO-7185 Standard Pascal does not define `import' and Modules in
general.  These are defined in the ISO-10206 Extended Pascal standard.

   GNU Pascal does not yet support `qualified' import.

See also
--------

   *Note Module::, *Note Unit::, *Note uses::.


File: gpc.info,  Node: Implementation,  Next: in,  Prev: import,  Up: Reference

Implementation
==============

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: in,  Next: inc,  Prev: Implementation,  Up: Reference

in
==

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: inc,  Next: Index,  Prev: in,  Up: Reference

inc
===

   (Under construction.)

Syntax
------

       Procedure inc ( Var x: ORDINAL TYPE );
   or
       Procedure inc ( Var x: ORDINAL TYPE; amount: Integer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Index,  Next: inherited,  Prev: inc,  Up: Reference

Index
=====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: inherited,  Next: inline,  Prev: Index,  Up: Reference

inherited
=========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: inline,  Next: InOutRes,  Prev: inherited,  Up: Reference

inline
======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: InOutRes,  Next: InOutResStr,  Prev: inline,  Up: Reference

InOutRes
========

   (Under construction.)

Syntax
------

       Var
         InOutRes: Integer;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: InOutResStr,  Next: Input,  Prev: InOutRes,  Up: Reference

InOutResStr
===========

   (Under construction.)

Syntax
------

       Var
         InOutResStr: CString;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Input,  Next: Insert,  Prev: InOutResStr,  Up: Reference

Input
=====

   (Under construction.)

Syntax
------

       Var
         Input: Text;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Insert,  Next: int,  Prev: Input,  Up: Reference

Insert
======

   (Under construction.)

Syntax
------

       Procedure Insert ( Source: String; Var Dest: String; Position: Integer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: int,  Next: Integer,  Prev: Insert,  Up: Reference

int
===

   (Under construction.)

Syntax
------

       Function int ( x: Real ): Real;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Integer,  Next: Interface,  Prev: int,  Up: Reference

Integer
=======

Description
-----------

   `Integer' is the "natural" signed integer type in GNU Pascal.  On
most platforms it is 32 bits wide and thus has a range of
`-2147483648..2147483647'.  Use it whenever you need a general-purpose
signed integer type.

   As an extension, GPC allows to use `Integer' as a pseudo-schema to
produce types with a specified size in bits; for example

       Type
         Int16 = Integer ( 16 );

   defines an integer type with 16 bits.  The same mechanism works for
`Cardinal' and `Word', too.

   `Integer' in GNU Pascal is compatible to `int' in GNU C.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   In ISO Pascal, `Integer' is the only built-in integer type.
(However see *Note Subrange types::.)

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: Interface,  Next: IOresult,  Prev: Integer,  Up: Reference

Interface
=========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: IOresult,  Next: Label,  Prev: Interface,  Up: Reference

IOresult
========

   (Under construction.)

Syntax
------

       Function IOresult: Integer;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Label,  Next: LastPosition,  Prev: IOresult,  Up: Reference

Label
=====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: LastPosition,  Next: le,  Prev: Label,  Up: Reference

LastPosition
============

   (Under construction.)

Syntax
------

       Function LastPosition ( Var F: TYPED FILE ): Integer;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: le,  Next: length,  Prev: LastPosition,  Up: Reference

le
==

   (Under construction.)

Syntax
------

       Function le ( S1, S2: String ): Boolean;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: length,  Next: ln,  Prev: le,  Up: Reference

length
======

   (Under construction.)

Syntax
------

       Function length ( S: String ): Integer;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: ln,  Next: LoCase,  Prev: length,  Up: Reference

ln
==

   (Under construction.)

Syntax
------

       Function ln ( x: Real ): Real;
   or
       Function ln ( z: Complex ): Complex;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: LoCase,  Next: LongCard,  Prev: ln,  Up: Reference

LoCase
======

   (Under construction.)

Syntax
------

       Function LoCase ( Ch: Char ): Char;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: LongCard,  Next: LongInt,  Prev: LoCase,  Up: Reference

LongCard
========

Description
-----------

   `LongCard' is an unsigned integer type which is longer than
`Cardinal'.  On most platforms it is 64 bits wide and thus has a range
of `0..18446744073709551615'.

   `LongCard' in GNU Pascal is compatible to `long long unsigned int'
in GNU C.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `LongCard'.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: LongInt,  Next: LongestCard,  Prev: LongCard,  Up: Reference

LongInt
=======

Description
-----------

   `LongInt' is a signed integer type which is longer than `Integer'.
On most platforms it is 64 bits wide and thus has a range of
`-9223372036854775808..9223372036854775807'.

   `LongInt' in GNU Pascal is compatible to `long long int' in GNU C.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `LongInt'.

   Borland Pascal and Delphi also define `LongInt', but it is a 32-bit
signed integer type there (*Note Integer:: in GNU Pascal).  Both
Borland languages define *Note Comp:: as a 64-bit signed integer type
which is also supported by GPC for compatibility.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: LongestCard,  Next: LongestInt,  Prev: LongInt,  Up: Reference

LongestCard
===========

Description
-----------

   `LongestCard' is GPC's longest-possible unsigned integer type.
Currently, this is the same as *Note LongCard::.  On most platforms it
is 64 bits wide and thus has a range of `0..18446744073709551615'.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `LongestCard'.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: LongestInt,  Next: LongestReal,  Prev: LongestCard,  Up: Reference

LongestInt
==========

Description
-----------

   `LongestInt' is GPC's longest-possible signed integer type.
Currently, this is the same as *Note LongInt::.  On most platforms it
is 64 bits wide and thus has a range of
`-9223372036854775808..9223372036854775807'.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `LongestInt'.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: LongestReal,  Next: LongestWord,  Prev: LongestInt,  Up: Reference

LongestReal
===========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: LongestWord,  Next: LongReal,  Prev: LongestReal,  Up: Reference

LongestWord
===========

Description
-----------

   `LongestWord' is GPC's longest-possible unsigned integer type.
Currently, this is the same as *Note LongWord::.  On most platforms it
is 64 bits wide and thus has a range of `0..18446744073709551615'.  (It
is the same as *Note LongestCard::.)

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `LongestWord'.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: LongReal,  Next: LongWord,  Prev: LongestWord,  Up: Reference

LongReal
========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: LongWord,  Next: low,  Prev: LongReal,  Up: Reference

LongWord
========

Description
-----------

   `LongWord' is an unsigned integer type which is larger than `Word'.
On most platforms it is 64 bits wide and thus has a range of
`0..18446744073709551615'.  It is the same as *Note LongCard::.

   `LongWord' in GNU Pascal is compatible to `long long unsigned int'
in GNU C.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `LongWord'.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: low,  Next: lt,  Prev: LongWord,  Up: Reference

low
===

   (Under construction.)

Syntax
------

Syntax
------

       Function low ( ORDINAL TYPE OR VARIABLE ): Integer;
   or
       Function low ( ARRAY TYPE OR VARIABLE ): Integer;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: lt,  Next: Mark,  Prev: low,  Up: Reference

lt
==

   (Under construction.)

Syntax
------

       Function lt ( S1, S2: String ): Boolean;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Mark,  Next: max,  Prev: lt,  Up: Reference

Mark
====

   (Under construction.)

Syntax
------

       Procedure Mark ( Var P: Pointer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: max,  Next: MaxChar,  Prev: Mark,  Up: Reference

max
===

   (Under construction.)

Syntax
------

       Function max ( x1, x2: ORDINAL OR REAL TYPE ): SAME TYPE;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: MaxChar,  Next: MaxInt,  Prev: max,  Up: Reference

MaxChar
=======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: MaxInt,  Next: MaxReal,  Prev: MaxChar,  Up: Reference

MaxInt
======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: MaxReal,  Next: MedCard,  Prev: MaxInt,  Up: Reference

MaxReal
=======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: MedCard,  Next: MedInt,  Prev: MaxReal,  Up: Reference

MedCard
=======

Description
-----------

   `MedCard' is an unsigned integer type which is not smaller than
`Cardinal'.  On most platforms it actually is the same as `Cardinal'
and 32 bits wide and thus has a range of `0..4294967295'.

   `MedCard' in GNU Pascal is compatible to `long unsigned int' in GNU
C.  This compatibility is the reason why `MedCard' exists.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `MedCard'.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: MedInt,  Next: MedReal,  Prev: MedCard,  Up: Reference

MedInt
======

Description
-----------

   `MedInt' is a signed integer type which is not smaller than
`Integer'.  On most platforms it actually is the same as `Integer' and
32 bits wide and thus has a range of `-2147483648..2147483647'.

   `MedInt' in GNU Pascal is compatible to `long int' in GNU C.  This
compatibility is the reason why `MedInt' exists.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `MedInt'.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: MedReal,  Next: MedWord,  Prev: MedInt,  Up: Reference

MedReal
=======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: MedWord,  Next: min,  Prev: MedReal,  Up: Reference

MedWord
=======

Description
-----------

   `MedWord' is an unsigned integer type which is not smaller than
`Word'.  On most platforms it actually is the same as `Word' and 32
bits wide and thus has a range of `0..4294967295'.  It is the same as
*Note MedCard::.

   `MedWord' in GNU Pascal is compatible to `long unsigned int' in GNU
C.  This compatibility is the reason why `MedWord' exists.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `MedWord'.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: min,  Next: MinReal,  Prev: MedWord,  Up: Reference

min
===

   (Under construction.)

Syntax
------

       Function min ( x1, x2: ORDINAL OR REAL TYPE ): SAME TYPE;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: MinReal,  Next: MkDir,  Prev: min,  Up: Reference

MinReal
=======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: MkDir,  Next: mod,  Prev: MinReal,  Up: Reference

MkDir
=====

   (Under construction.)

Syntax
------

       Procedure MkDir ( Directory: String );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: mod,  Next: Module,  Prev: MkDir,  Up: Reference

mod
===

   (Under construction.)

Syntax
------

       Operator mod ( p, q: Integer ) = r: Integer;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Module,  Next: move,  Prev: mod,  Up: Reference

Module
======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: move,  Next: MoveLeft,  Prev: Module,  Up: Reference

move
====

   (Under construction.)

Syntax
------

       Procedure move ( Const Source; Var Dest; Count: Integer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: MoveLeft,  Next: MoveRight,  Prev: move,  Up: Reference

MoveLeft
========

   (Under construction.)

Syntax
------

       Procedure MoveLeft ( Const Source; Var Dest; Count: Integer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: MoveRight,  Next: near,  Prev: MoveLeft,  Up: Reference

MoveRight
=========

   (Under construction.)

Syntax
------

       Procedure MoveRight ( Const Source; Var Dest; Count: Integer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: near,  Next: ne,  Prev: MoveRight,  Up: Reference

near
====

Description
-----------

   The `near' directive can be appended to a procedure or function
heading but is ignored by GPC.  It is there for Borland compatibility,
only.  (Since the GNU compilers provide a flat memory model, the
distinction between `near' and `near' pointers is void.)

Standards
---------

   ISO Pascal does not define `near', Borland Pascal does.

Example
-------

       Var
         p: Procedure;
     
       Procedure Foo; near;  (* `near' has no effect in GPC *)
     
       begin (* Foo *)
         [...]
       end (* Foo *);
     
       [...]
     
       p:= Foo;  (* Works, despite the `near'. *)

See also
--------

   *Note far::.


File: gpc.info,  Node: ne,  Next: New,  Prev: near,  Up: Reference

ne
==

   (Under construction.)

Syntax
------

       Function ne ( S1, S2: String ): Boolean;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: New,  Next: NewCString,  Prev: ne,  Up: Reference

New
===

   (Under construction.)

Syntax
------

       Procedure New ( Var P: ANY POINTER );
   or
       Procedure New ( Var P: POINTER TO A VARIANT RECORD; TAG FIELDS);
   or
       Procedure New ( Var P: POINTER TO A SCHEMA; DISCRIMINANTS);
   or
       Procedure New ( Var P: POINTER TO AN OBJECT; CONSTRUCTOR CALL);
   or
       Function New ( ANY POINTER TYPE ): SAME TYPE;
   or
       Function New ( VARIANT RECORD POINTER TYPE;
                      TAG FIELDS): SAME TYPE;
   or
       Function New ( SCHEMA POINTER TYPE;
                      DISCRIMINANTS): SAME TYPE;
   or
       Function New ( OBJECT POINTER TYPE;
                      CONSTRUCTOR CALL): SAME TYPE;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: NewCString,  Next: Nil,  Prev: New,  Up: Reference

NewCString
==========

   (Under construction.)

Syntax
------

       Function NewCString ( Const S: String ): CString;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Nil,  Next: not,  Prev: NewCString,  Up: Reference

Nil
===

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: not,  Next: NULL,  Prev: Nil,  Up: Reference

not
===

   (Under construction.)

Syntax
------

       Operator not ( b1, b2: Boolean ) = result: Boolean;
   or
       Operator not ( i1, i2: INTEGER TYPE ) = result: INTEGER TYPE;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: NULL,  Next: object,  Prev: not,  Up: Reference

NULL
====

   (Under construction.)

Syntax
------

       Var NULL: Void absolute 0;

Description
-----------

   Variable at address `Nil'.

Standards
---------

   Delphi

Example
-------

See also
--------

   *Note Nil::.


File: gpc.info,  Node: object,  Next: odd,  Prev: NULL,  Up: Reference

object
======

Description
-----------

   The keyword `object' is used to declare a new object type:

       Type
         foo = object
           a: Integer;
           Constructor Init;
           Procedure bar ( x: Integer ); virtual;
         end (* foo *);

   (For a longer example, see *Note OOP::.)

Standards
---------

   GNU Pascal follows the Borland Pascal 7.0 object model.

   ISO Pascal does not support Object-orientated programming.  There is
an ANSI draft for an "Object Pascal" language which is not yet
supported by GPC, but planned.  The Delphi language, also called
"Object Pascal" by Borland, is currently not supported by GPC either.

See also
--------

   *Note OOP::, *Note record::.


File: gpc.info,  Node: odd,  Next: of,  Prev: object,  Up: Reference

odd
===

   (Under construction.)

Syntax
------

       Function odd ( i: Integer ): Boolean;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: of,  Next: only,  Prev: odd,  Up: Reference

of
==

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: only,  Next: Operator,  Prev: of,  Up: Reference

only
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Operator,  Next: or,  Prev: only,  Up: Reference

Operator
========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: or,  Next: or else,  Prev: Operator,  Up: Reference

or
==

Syntax
------

       Operator or ( operand1, operand2: Boolean ) = result: Boolean;
   or
       Operator or ( operand1, operand2: INTEGER TYPE ) = result: INTEGER TYPE;
   or
       Procedure or ( Var operand1: INTEGER TYPE; operand2: INTEGER TYPE );

Description
-----------

   In GNU Pascal, `or' has three built-in meanings:

  1. Logical "or" between two `Boolean'-type expressions.  The result
     of the operation is of `Boolean' type.

     By default, `or' acts as a short-circuit operator in GPC:  If the
     first operand is `true', the second operand is not evaluated
     because the result is already known to be `true'.  You can change
     this to complete evaluation using the `--no-short-circuit'
     command-line option or the `(*$B+*)' compiler directive.

  2. Bitwise "or" between two integer-type expressions.  The result is
     of the common integer type of both expressions.

  3. Use as a "procedure":  `operand1' is "or"ed bitwise with
     `operand2'; the result is stored in `operand1'.


Standards
---------

   The logical `or' operator is defined in ISO-7185 Standard Pascal.

   According to ISO, you cannot rely on `or' being a short-circuit
operator.  On the other hand, GPC's default behaviour does *not*
contradict the ISO standard.  (See *Note or_else::.)  However, since it
seems to be a de-facto standard among ISO Pascal compilers to evaluate
both operands of `or', GPC switches to `--no-short-circuit' mode if one
of the language dialect options selecting ISO Pascal, for instance
`--extended-pascal', is given.  Use `--short-circuit' to override.

   ISO Pascal does not define the bitwise `or' operator; Borland Pascal
and Delphi do.

   Use of `or' as a "procedure" is a GNU extension.

Example
-------

       Var
         a, b, c: Integer;
     
       ...
     
       if ( a = 0 ) or ( b = 0 ) then  (* logical `or' *)
         c:= 1
       else if a or b = 0 then  (* bitwise `or' *)
         c:= 2
       else
         or ( c, a );  (* same as `c:= c or a' *)

   Note the difference between the logical `or' and the bitwise `or':
When `a' is 2 and `b' is 4, then `a or b' is 6.  *Beware:*  `a or b =
0' happens to mean the same as `( a = 0 ) and ( b = 0 )'.  (Note the
`and'!)

   Since bitwise `or' has a higher priority than the `=' operator,
parentheses are needed in `if ( a = 0 ) or ( b = 0 )' because otherwise
`0 or b' would be calculated first, and the remainder would cause a
parse error.

See also
--------

   *Note and::, *Note xor::, *Note Operators::.


File: gpc.info,  Node: or else,  Next: or_else,  Prev: or,  Up: Reference

or else
=======

Description
-----------

   `or else' is an alias for the short-circuit logical operator
`or_else'.

Standards
---------

   While `or_else' is defined in ISO-10206 Extended Pascal, `or else'
is a GNU Extension.

Example
-------

       Var
         a: Integer;
     
       [...]
     
       if ( a = 0 ) or else ( 100 div a > 42 ) then  (* This is safe. *)
         [...];

See also
--------

   *Note or_else::, *Note or::, *Note and then::.


File: gpc.info,  Node: or_else,  Next: ord,  Prev: or else,  Up: Reference

or_else
=======

Syntax
------

       Operator or_else ( operand1, operand2: Boolean ) = result: Boolean;

Description
-----------

   The `or_else' short-circuit logical operator performs the same
operation as the logical operator `or'.  But while the ISO standard
does not specify anything about the evaluation of the operands of
`or'--they may be evaluated in any order, or not at all--`or_else' has
a well-defined behaviour:  It evaluates the first operand.  If the
result is `true', `or_else' returns `true' without evaluating the
second operand.  If it is `false', the second operand is evaluated and
returned.

   Since the behaviour described above is the most effective way to
implement `or', GPC by default treats `or' and `or_else' exactly the
same.  If you want, for some reason, to have both operands of `or'
evaluated completely, you can specify the `--no-short-circuit'
command-line option, but this is not portable.  The portable way to
have both operands evaluated is to assign both to temporary variables
and then use `or'--or `or_else', it does not matter.

Standards
---------

   ISO-7185 Standard Pascal does not define `or_else'; ISO-10206
Extended Pascal does.

   Some people think that the ISO standard requires both operands of
`or' to be evaluated.  This is false.  What the ISO standard *does* say
is that you cannot rely on a certain order of evaluation of the
operands of `or'; in particular things like

       Var
         a: Integer;
     
       [...]
     
       if ( a = 0 ) or ( 100 div a > 42 ) then
         [...];

can crash according to ISO Pascal, although they cannot crash when
compiled with GNU Pascal running in default mode.

   If you want to write portable and efficient code in ISO-10206
Extended Pascal, *always* use `or_else'; *never* use `or'.

Example
-------

       Var
         a: Integer;
     
       [...]
     
       if ( a = 0 ) or_else ( 100 div a > 42 ) then  (* This is safe. *)
         [...];

See also
--------

   *Note or else::, *Note or::, *Note and_then::.


File: gpc.info,  Node: ord,  Next: others,  Prev: or_else,  Up: Reference

ord
===

   (Under construction.)

Syntax
------

       Function ord ( Ch: Char ): Integer;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: others,  Next: otherwise,  Prev: ord,  Up: Reference

others
======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: otherwise,  Next: Output,  Prev: others,  Up: Reference

otherwise
=========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Output,  Next: pack,  Prev: otherwise,  Up: Reference

Output
======

   (Under construction.)

Syntax
------

       Var
         Output: Text;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: pack,  Next: packed,  Prev: Output,  Up: Reference

pack
====

   (Under construction.)

Syntax
------

Description
-----------

       Procedure pack ( Source: UNPACKED ARRAY;
                        FirstElement: INDEX TYPE;
                        Var Dest: PACKED ARRAY );

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: packed,  Next: page,  Prev: pack,  Up: Reference

packed
======

Description
-----------

   `packed' is a reserved word.  According to ISO-7185 Standard Pascal
it can preceed `array' and `record' type definitions to indicate that
memory usage should be minimized for variables of this type, possibly
at the expense of loss of speed.

   As a GNU extension, `packed' can also be applied to *Note Subrange
types::.

Standards
---------

   The reserved word `packed' is defined in ISO-7185 Standard Pascal.

   According to ISO standard, only *packed* arrays of char with lower
bound 1 qualify as strings of fixed length.  GNU Pascal neither requires
`packed' nor the lower bound of 1 here.

Example
-------

       Type
         MonthInt = packed 1..12;  (* needs one byte   *)
         FastMonthInt = 1..12;     (* needs four bytes *)
     
         FixString10 = packed array [ 1..10 ] of Char;
         FoxyString10 = array [ 0..9 ] of Char;
     
         Flags = packed array [ 1..32 ] of Boolean;  (* needs four Bytes *)
     
         DateRec = packed record
           day: 1..31;            (* five bits *)
           month: MonthInt;       (* four bits *)
           year: Integer ( 15 );  (* 15 bits = -16384..16383 *)
         end (* DateRec *);
     
         Dates = array [ 1..1000 ] of DateRec;
     
       Var
         S: FixString10;
         T: FoxyString10;
     
       [...]
     
       S:= 'Hello!';   (* blank padded *)
       writeln ( S );
     
       T:= 'GNU Pascal';  (* GPC extension: this also works. *)
       writeln ( T );

   `DateRec' has 24 bits = 3 bytes in total; `Dates' has 3000 bytes.

See also
--------

   *Note pack::, *Note unpack::, *Note SizeOf::, *Note AlignOf::, *Note
BitSizeOf::.


File: gpc.info,  Node: page,  Next: pAnsiChar,  Prev: packed,  Up: Reference

page
====

   (Under construction.)

Syntax
------

       Procedure Page ( Var F: Text );
   or
       Procedure Page;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: pAnsiChar,  Next: ParamCount,  Prev: page,  Up: Reference

pAnsiChar
=========

   (Under construction.)

Syntax
------

       Type
         pAnsiChar = ^AnsiChar;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: ParamCount,  Next: ParamStr,  Prev: pAnsiChar,  Up: Reference

ParamCount
==========

Syntax
------

       Function ParamCount: Integer;

Description
-----------

   `ParamCount' returns the number of command-line arguments given to
the program.  `ParamCount' returns 0 if no arguments have been given to
the program; the name of the program as an implicit argument is not
counted.

Standards
---------

   `ParamCount' is a Borland Pascal extension.

Example
-------

       Program Test;
     
       Var
         i: Integer;
     
       begin
         writeln ( 'You have invoked this program with ',
                   ParamCount, ' arguments.' );
         writeln ( 'These are:' );
         for i:= 1 to ParamCount do
           writeln ( ParamStr ( i ) );
       end.

See also
--------

   *Note ParamStr::.


File: gpc.info,  Node: ParamStr,  Next: pChar,  Prev: ParamCount,  Up: Reference

ParamStr
========

   (Under construction.)

Syntax
------

       Function ParamStr ( ParmNumber: Integer ): String;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: pChar,  Next: Pointer,  Prev: ParamStr,  Up: Reference

pChar
=====

   (Under construction.)

Syntax
------

       Type
         pChar = ^Char;
   or
       Type
         pChar = CString;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Pointer,  Next: polar,  Prev: pChar,  Up: Reference

Pointer
=======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: polar,  Next: pos,  Prev: Pointer,  Up: Reference

polar
=====

   (Under construction.)

Syntax
------

       Function polar ( rho, phi: Real ): Complex;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: pos,  Next: Position,  Prev: polar,  Up: Reference

pos
===

   (Under construction.)

Syntax
------

       Function pos ( SearchPattern, Source: String ): Integer;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Position,  Next: pow,  Prev: pos,  Up: Reference

Position
========

   (Under construction.)

Syntax
------

       Function Position ( Var F: TYPED FILE );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: pow,  Next: pred,  Prev: Position,  Up: Reference

pow
===

   (Under construction.)

Syntax
------

       Operator pow ( base: Real; exponent: Integer ) = power: Real;
   or
       Operator pow ( base: Complex; exponent: Integer ) = power: Complex;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: pred,  Next: Procedure,  Prev: pow,  Up: Reference

pred
====

Syntax
------

       Function pred ( i: ORDINAL TYPE ): ORDINAL TYPE;
   or
       Function pred ( i: ORDINAL TYPE; j: Integer ): ORDINAL TYPE;

   or, with extended syntax (`--extended-syntax' or `(*$X+*)'),

       Function pred ( p: POINTER TYPE ): POINTER TYPE;
   or
       Function pred ( p: POINTER TYPE; j: Integer ): POINTER TYPE;

Description
-----------

   Returns the predecessor of the ORDINAL TYPE value `i', or, if the
second argument `j' is given, its `j'th predecessor.  For integer
values `i', this is `i - 1' (or `i - j').  (No, `pred' does *not* work
faster than plain subtraction.  Both are optimized to a single machine
instruction or even expanded by the compiler, if possible.)

   If extended syntax is on, the argument may also be a pointer value.
In this case, the address is decremented by the size of the variable
pointed to, or, if `j' is given, by `j' times the size of the variable
pointed to.  If `p' points to an element of an array, the returned
pointer will point to the (`j'th) previous element of the array.

Standards
---------

   The `pred' function is defined in ISO-7185 Standard Pascal.  The
optional second parameter is defined in ISO-10206 Extended Pascal.
Application of `pred' to pointers is defined in Borland Pascal.  The
combination of the second argument with application to pointers is a
GNU extension.

Example
-------

       Program PredTest;
     
       Type
         Metasyntactical = ( foo, bar, baz );
     
       Var
         m: Metasyntactical;
         c: Char;
         a: array [ 1..7 ] of Integer;
         p: ^Integer;
     
       begin
         m:= pred ( bar );     (* foo *)
         c:= pred ( 'Z', 2 );  (* 'X' *)
         a [ 1 ]:= 42;
         a [ 4 ]:= pred ( a [ 1 ] );     (* 41 *)
         a [ 5 ]:= pred ( a [ 4 ], 3 );  (* 38 *)
         (*$X+*)
         p:= @a [ 5 ];
         p:= pred ( p );     (* now points to `a [ 4 ]' *)
         p:= pred ( p, 3 );  (* now points to `a [ 1 ]' *)
       end.

See also
--------

   *Note succ::, *Note dec::, *Note Pointer arithmetics::.


File: gpc.info,  Node: Procedure,  Next: Program,  Prev: pred,  Up: Reference

Procedure
=========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Program,  Next: protected,  Prev: Procedure,  Up: Reference

Program
=======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: protected,  Next: PtrCard,  Prev: Program,  Up: Reference

protected
=========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: PtrCard,  Next: PtrInt,  Prev: protected,  Up: Reference

PtrCard
=======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: PtrInt,  Next: PtrWord,  Prev: PtrCard,  Up: Reference

PtrInt
======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: PtrWord,  Next: Put,  Prev: PtrInt,  Up: Reference

PtrWord
=======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Put,  Next: Re,  Prev: PtrWord,  Up: Reference

Put
===

   (Under construction.)

Syntax
------

       Procedure Put ( Var F: TYPED FILE );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Re,  Next: read,  Prev: Put,  Up: Reference

Re
==

   (Under construction.)

Syntax
------

       Function Re ( z: Complex ): Real;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: read,  Next: readln,  Prev: Re,  Up: Reference

read
====

   (Under construction.)

Syntax
------

       Procedure read ( Var F: TYPED FILE; VARIABLE );
   or
       Procedure read ( Var F: Text; VARIABLES );
   or
       Procedure read ( VARIABLES );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: readln,  Next: ReadStr,  Prev: read,  Up: Reference

readln
======

   (Under construction.)

Syntax
------

       Procedure readln ( Var F: Text; VARIABLES );
   or
       Procedure readln ( VARIABLES );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: ReadStr,  Next: Real,  Prev: readln,  Up: Reference

ReadStr
=======

   (Under construction.)

Syntax
------

       Procedure ReadStr ( Const S: String; VARIABLES );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Real,  Next: record,  Prev: ReadStr,  Up: Reference

Real
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: record,  Next: Release,  Prev: Real,  Up: Reference

record
======

Description
-----------

   The reserved word `record' starts the definition of a new record
type.  The syntax is

       foo = record
         FIELD DECLARATIONS
       end (* foo *);

   or, with a variant part,

       foo = record
         FIELD DECLARATIONS
         case bar: VARIANT TYPE of
           SELECTOR: ( FIELD DECLARATIONS );
           SELECTOR: ( FIELD DECLARATIONS );
           ...
       end (* foo *);

   or, without a variant selector field,

       foo = record
         FIELD DECLARATIONS
         case VARIANT TYPE of
           SELECTOR: ( FIELD DECLARATIONS );
           SELECTOR: ( FIELD DECLARATIONS );
           ...
       end (* foo *);

   Records can be `packed' to save memory usage at the expense of speed.

   The variants of a variant record share one location in memory
(inside the record) and thus can be used to emulate type casting
without violating ISO-7185 Standard Pascal.

Standards
---------

   The reserved word `record' and record types are defined in ISO-7185
Standard Pascal.

   According to ISO Pascal, the variant type must be an identifier.
GNU Pascal, like UCSD and Borland Pascal, also allows a subrange here.

Example
-------

       Type
         fooPtr = ^foo;
     
         foo = record
           bar: Integer;
           nextFoo: fooPtr;
           case choice: 1..3 of
             1: ( a: Integer );   (* These three choices share *)
             2: ( b: Real );      (* one location in memory.   *)
             3: ( c: Char;
                  d: Boolean );
         end (* foo *);
     
         smallFoo = packed record
           b: 0..3;
           a: Integer ( 5 );
           r: Boolean;
         end (* smallFoo *);   (* needs 1 byte *)
     
       Var
         f: foo;
     
       [...]
     
       f.b:= 3.14;
       writeln ( f.a );  (* yields some strange number which is part of the   *)
                         (* internal representation of the real number `f.b'. *)

See also
--------

   *Note packed::, *Note array::, *Note object::.


File: gpc.info,  Node: Release,  Next: rename,  Prev: record,  Up: Reference

Release
=======

   (Under construction.)

Syntax
------

       Procedure Release ( P: Pointer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: rename,  Next: repeat,  Prev: Release,  Up: Reference

rename
======

   (Under construction.)

Syntax
------

       Procedure Rename ( Var F: ANY FILE; NewName: String );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: repeat,  Next: reset,  Prev: rename,  Up: Reference

repeat
======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: reset,  Next: restricted,  Prev: repeat,  Up: Reference

reset
=====

   (Under construction.)

Syntax
------

       Procedure reset ( Var F: ANY FILE );
   or
       Procedure reset ( Var F: ANY FILE; FileName: String );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: restricted,  Next: Result,  Prev: reset,  Up: Reference

restricted
==========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Result,  Next: return,  Prev: restricted,  Up: Reference

Result
======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: return,  Next: rewrite,  Prev: Result,  Up: Reference

return
======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: rewrite,  Next: RmDir,  Prev: return,  Up: Reference

rewrite
=======

   (Under construction.)

Syntax
------

       Procedure rewrite ( Var F: ANY FILE );
   or
       Procedure rewrite ( Var F: ANY FILE; FileName: String );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: RmDir,  Next: round,  Prev: rewrite,  Up: Reference

RmDir
=====

   (Under construction.)

Syntax
------

       Procedure RmDir ( Directory: String );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: round,  Next: RunError,  Prev: RmDir,  Up: Reference

round
=====

   (Under construction.)

Syntax
------

       Function round ( x: Real ): Integer;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: RunError,  Next: Seek,  Prev: round,  Up: Reference

RunError
========

   (Under construction.)

Syntax
------

       Procedure RunError ( ErrorCode: Integer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Seek,  Next: SeekRead,  Prev: RunError,  Up: Reference

Seek
====

   (Under construction.)

Syntax
------

       Procedure Seek ( Var F: TYPED FILE; NewPosition: Integer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: SeekRead,  Next: SeekUpdate,  Prev: Seek,  Up: Reference

SeekRead
========

   (Under construction.)

Syntax
------

       Procedure SeekRead ( Var F: TYPED FILE; NewPosition: Integer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: SeekUpdate,  Next: SeekWrite,  Prev: SeekRead,  Up: Reference

SeekUpdate
==========

   (Under construction.)

Syntax
------

       Procedure SeekUpdate ( Var F: TYPED FILE; NewPosition: Integer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: SeekWrite,  Next: Self,  Prev: SeekUpdate,  Up: Reference

SeekWrite
=========

   (Under construction.)

Syntax
------

       Procedure SeekWrite ( Var F: TYPED FILE; NewPosition: Integer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Self,  Next: set,  Prev: SeekWrite,  Up: Reference

Self
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: set,  Next: SetLength,  Prev: Self,  Up: Reference

set
===

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: SetLength,  Next: SetType,  Prev: set,  Up: Reference

SetLength
=========

Syntax
------

       Procedure SetLength ( Var S: String; NewLength: Integer );

Description
-----------

   `SetLength' explicitly assigns a new length `NewLength' to the
string parameter `S'.  The contents of the string is *not* changed; if
the operation increases the length of the string, the characters
appended at the end are *undefined*.

   If you want to use `SetLength', please enable "extended syntax"
(`--extended-syntax' or `(*$X+*)').

Standards
---------

   `SetLength' is a Borland Delphi 2.0 extension.

Example
-------

     Program TestSetLength;
     
     (*$X+*)  (* Enable "dangerous" features *)
     
     Var
       S: String ( 26 );
     
     begin
       S:= 'Hello, world!';
       SetLength ( S, length ( 'Hello' ) );
       writeln ( S );                                     (* 'Hello' *)
       SetLength ( S, 26 );
       writeln ( S );               (* 'Hello, world!(%$@§"!"§$§"$'  *)
                             (* undefined characters ^^^^^^^^^^^^^   *)
     
       SetLength ( S, 42 );  (* The overflow is *not* (yet) detected *)
       writeln ( S );        (* This might cause a runtime error.    *)
     end.

See also
--------

   *Note length::, *Note String::, *Note SetType::.


File: gpc.info,  Node: SetType,  Next: ShortCard,  Prev: SetLength,  Up: Reference

SetType
=======

Syntax
------

       Procedure SetType ( Var SomeObject; VMT: Pointer );

Description
-----------

   The procedure `SetType' explicitly assigns a value to the implicit
VMT field of an object.  This is normally done implicitly when a
constructor is called.

   You can use this to write a polymorphic I/O routine which reads an
object from a file.  In this case, you cannot reasonably use `New' to
allocate the storage, but you `GetMem' it and initialize the object
manually using `SetType' before calling the constructor explicitly.

   This is a dangerous feature which yields a warning unless `(*$X+*)'
is given.

Standards
---------

   `SetType' is a GNU extension.

Example
-------

       (*$X+*)
     
       Type
         BasePtr = ^BaseObj;
     
         BaseObj = object
           Constructor Load;
         end (* BaseObj *)
     
         [Successor objects ...]
     
       [...]
     
       Function GetObject = Result: BasePtr;
     
       Var
         Size: Cardinal;
         VMT: Pointer;
     
       begin (* GetObject *)
         [Read the size of the object from some file and store it in `Size'.]
         GetMem ( Result, Size );
         [Read some ID from some file and look up the `VMT' from some table.]
         SetType ( Result^, VMT );
         (* Now the object is ready, and the constructor can be called. *)
         [Look up the correct constructor from some table and call it.]
       end (* GetObject *);

See also
--------

   *Note TypeOf::, *Note OOP::.


File: gpc.info,  Node: ShortCard,  Next: ShortInt,  Prev: SetType,  Up: Reference

ShortCard
=========

Description
-----------

   `ShortCard' is an unsigned integer type which is not larger than
`Cardinal'.  On most platforms it is 16 bits wide and thus has a range
of `0..65535'.

   `ShortCard' in GNU Pascal is compatible to `short unsigned int' in
GNU C.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `ShortCard'.  (However see *Note Subrange
types::.)

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: ShortInt,  Next: ShortReal,  Prev: ShortCard,  Up: Reference

ShortInt
========

Description
-----------

   `ShortInt' is a signed integer type which is not larger than
`Integer'.  On most platforms it is 16 bits wide and thus has a range
of `-32768..32767'.

   `ShortInt' in GNU Pascal is compatible to `short int' in GNU C.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `ShortInt'.  (However see *Note Subrange
types::.)

   `ShortInt' in GNU Pascal corresponds to `Integer' in Borland Pascal
and Delphi 1.0.  Both Borland languages also define `ShortInt', but it
is an 8-bit signed integer type there (`ByteInt' in GNU Pascal).

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: ShortReal,  Next: ShortWord,  Prev: ShortInt,  Up: Reference

ShortReal
=========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: ShortWord,  Next: Single,  Prev: ShortReal,  Up: Reference

ShortWord
=========

Description
-----------

   `ShortWord' is an unsigned integer type which is not larger than
`Word'.  On most platforms it is 16 bits wide and thus has a range of
of `0..65535'.  It is the same as *Note ShortCard::.

   `ShortWord' in GNU Pascal is compatible to `short unsigned int' in
GNU C.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `ShortWord'.  (However see *Note Subrange
types::.)

   `ShortWord' in GNU Pascal essentially corresponds to `Word' in
Borland Pascal and Delphi where it is a 16-bit unsigned integer type.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: Single,  Next: shl,  Prev: ShortWord,  Up: Reference

Single
======

   (Under construction.)

Syntax
------

       Type
         Single = ShortReal;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: shl,  Next: shr,  Prev: Single,  Up: Reference

shl
===

Syntax
------

       Operator shl ( operand1, operand2: INTEGER TYPE ) = result: INTEGER TYPE;
   or
       Procedure shl ( Var operand1: INTEGER TYPE; operand2: INTEGER TYPE );

Description
-----------

   In GNU Pascal, `shl' has two built-in meanings:

  1. Bitwise shift left of an integer-type expression by another
     integer value.  The result is of the type of the first operand.

  2. Use as a "procedure":  `operand1' is shifted left by `operand2';
     the result is stored in `operand1'.


Standards
---------

   ISO Pascal does not define the `shl' operator; Borland Pascal and
Delphi do.

   Use of `shl' as a "procedure" is a GNU extension.

Example
-------

       Var
         a: Integer;
     
       ...
     
       a:= 1 shl 7;  (* yields 128 = 2 pow 7 *)
       shl ( a, 4 );  (* same as `a:= a shl 4' *)

See also
--------

   *Note shr::, *Note Operators::.


File: gpc.info,  Node: shr,  Next: sin,  Prev: shl,  Up: Reference

shr
===

Syntax
------

       Operator shr ( operand1, operand2: INTEGER TYPE ) = result: INTEGER TYPE;
   or
       Procedure shr ( Var operand1: INTEGER TYPE; operand2: INTEGER TYPE );

Description
-----------

   In GNU Pascal, `shr' has two built-in meanings:

  1. Bitwise shift right of an integer-type expression by another
     integer value.  The result is of the type of the first operand.

  2. Use as a "procedure":  `operand1' is shifted right by `operand2';
     the result is stored in `operand1'.


Standards
---------

   ISO Pascal does not define the bitwise `shr' operator; Borland
Pascal and Delphi do.

   Unlike the Borland compilers, GNU Pascal cares about the signedness
of the first operand:  If a signed integer with a negative value is
shifted right, "one" bits are filled in from the left.

   Use of `shr' as a "procedure" is a GNU extension.

Example
-------

       Var
         a: Integer;
     
       ...
     
       a:= 1024 shr 4;  (* yields 64 *)
       a:= -127 shr 4;  (* yields -7 *)
       shr ( a, 2 );  (* same as `a:= a shr 2' *)

See also
--------

   *Note shl::, *Note Operators::.


File: gpc.info,  Node: sin,  Next: SizeOf,  Prev: shr,  Up: Reference

sin
===

   (Under construction.)

Syntax
------

       Function sin ( x: Real ): Real;
   or
       Function sin ( z: Complex ): Complex;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: SizeOf,  Next: SmallInt,  Prev: sin,  Up: Reference

SizeOf
======

Syntax
------

       Function SizeOf ( Var x ): Integer;

Description
-----------

   Returns the size of a type or variable in bytes.

Standards
---------

   ISO Pascal does not define `SizeOf'; UCSD and Borland Pascal do.

Example
-------

       Var
         a: Integer;
         b: array [ 1..8 ] of Char;
     
       ...
     
       writeln ( SizeOf ( a ) );  (* Size of an `Integer'; usually 4 bytes. *)
       writeln ( SizeOf ( b ) );  (* Size of eight `Char's; usually 8 bytes. *)

See also
--------

   *Note BitSizeOf::, *Note AlignOf::, *Note TypeOf::.


File: gpc.info,  Node: SmallInt,  Next: sqr,  Prev: SizeOf,  Up: Reference

SmallInt
========

Description
-----------

   `SmallInt' is a signed integer type which is not larger than
`Integer'.  On most platforms it is 16 bits wide and thus has a range
of `-32768..32767'.  It is the same as `ShortInt' (see *Note
ShortInt::).

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `SmallInt'.  (However see *Note Subrange
types::.)

   `SmallInt' also appears in Delphi 2.0.  This compatibility is the
reason why GPC supports the synonym `SmallInt' for `ShortInt'.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: sqr,  Next: sqrt,  Prev: SmallInt,  Up: Reference

sqr
===

Syntax
------

       Function sqr ( i: INTEGER TYPE ): INTEGER TYPE;
   or
       Function sqr ( x: REAL TYPE ): REAL TYPE;
   or
       Function sqr ( z: COMPLEX TYPE ): COMPLEX TYPE;

Description
-----------

   Returns the square of the argument:

       Function sqr ( x: SOME TYPE ): SOME TYPE;
     
       begin (* sqr *)
         sqr:= x * x;  (* or: x pow 2 *)
       end (* sqr *);

Standards
---------

   The function `sqr' is defined in ISO-7185 Standard Pascal; its
application to complex values is defined in ISO-10206 Extended Pascal.

Example
-------

       Program TestSqr;
     
       Var
         i: Complex;
     
       begin
         i:= cmplx ( 0, 1 );
         writeln ( Re ( sqr ( i ) : 0 : 3 );
         (* yields -1.000 *)
       end.

See also
--------

   *Note pow::, *Note sqrt::, *Note abs::, *Note Operators::.


File: gpc.info,  Node: sqrt,  Next: StandardError,  Prev: sqr,  Up: Reference

sqrt
====

Syntax
------

       Function sqrt ( x: REAL TYPE ): REAL TYPE;
   or
       Function sqrt ( z: COMPLEX TYPE ): COMPLEX TYPE;

Description
-----------

   Returns the positive square root of the argument.

   For real arguments, it is an error if the argument is negative.

   For complex arguments, `sqrt' returns the principal value of the
root of the argument, i.e. the root with positive real part, or, if the
real part is zero, that one with positive imaginary part.

Standards
---------

   The function `sqrt' is defined in ISO-7185 Standard Pascal; its
application to complex values is defined in ISO-10206 Extended Pascal.

Example
-------

       Program TestSqrt;
     
       Var
         m1: Complex;
     
       begin
         m1:= cmplx ( -1, 0 );  (* -1 *)
         writeln ( Re ( sqrt ( m1 ) ) : 6 : 3, Im ( sqrt ( m1 ) ) : 6 : 3 );
         (* yields 1.000 -1.000, i.e. the imaginary unit, i *)
       end.

See also
--------

   *Note pow::, *Note sqr::, *Note Operators::.


File: gpc.info,  Node: StandardError,  Next: StandardInput,  Prev: sqrt,  Up: Reference

StandardError
=============

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: StandardInput,  Next: StandardOutput,  Prev: StandardError,  Up: Reference

StandardInput
=============

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: StandardOutput,  Next: static,  Prev: StandardInput,  Up: Reference

StandardOutput
==============

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: static,  Next: StdErr,  Prev: StandardOutput,  Up: Reference

static
======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: StdErr,  Next: Str,  Prev: static,  Up: Reference

StdErr
======

   (Under construction.)

Syntax
------

       Var
         StdErr: Text;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Str,  Next: StrPCopy,  Prev: StdErr,  Up: Reference

Str
===

   (Under construction.)

Syntax
------

       Procedure Str ( x: INTEGER OR REAL; Var Dest: String );
   or
       Procedure Str ( x: INTEGER OR REAL : FIELD WIDTH; Var Dest: String );
   or
       Procedure Str ( x: Real : FIELD WIDTH : PRECISION; Var Dest: String );
   or
       Procedure Str ( REPEATED CONSTRUCTS AS DESCRIBED ABOVE; Var Dest: String );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: StrPCopy,  Next: String,  Prev: Str,  Up: Reference

StrPCopy
========

   (Under construction.)

Syntax
------

       Function StrPCopy ( Dest: CString; Const Source: String ): CString;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: String,  Next: String2CString,  Prev: StrPCopy,  Up: Reference

String
======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: String2CString,  Next: SubStr,  Prev: String,  Up: Reference

String2CString
==============

   (Under construction.)

Syntax
------

       Function String2CString ( Const S: String ): CString;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: SubStr,  Next: succ,  Prev: String2CString,  Up: Reference

SubStr
======

Syntax
------

       Function SubStr ( S: String; FirstChar: Integer ): String;
   or
       Function SubStr ( S: String; FirstChar, Count: Integer ): String;

Description
-----------

   `SubStr' returns a sub-string of S starting with the character at
position FIRSTCHAR.  If COUNT is given, such many characters will be
copied into the sub-string.  If COUNT is omitted, the sub-string will
will range to the end of S.

   If `Count' is too large for the sub-string to fit in S or if
`FirstChar' exceeds the length of S, `SubStr' triggers a runtime error.
(For a function returning the empty string instead, see *Note Copy::.)

Standards
---------

   `SubStr' is defined in ISO 10206 Extended Pascal and does not appear
in Standard Pascal.

Example
-------

       Var
         S: String ( 42 );
     
       [...]
     
       S:= 'Hello';
       writeln ( SubStr ( S, 2, 3 ) );   (* yields "ell" *)
       writeln ( SubStr ( S, 3 ) );      (* yields "llo" *)
       writeln ( SubStr ( S, 4, 7 ) );   (* yields a runtime error *)
       writeln ( SubStr ( S, 42 ) );     (* yields a runtime error *)

See also
--------

   *Note Copy::, String slice access.


File: gpc.info,  Node: succ,  Next: Text,  Prev: SubStr,  Up: Reference

succ
====

Syntax
------

       Function succ ( i: ORDINAL TYPE ): ORDINAL TYPE;
   or
       Function succ ( i: ORDINAL TYPE; j: Integer ): ORDINAL TYPE;

   or, with extended syntax (`--extended-syntax' or `(*$X+*)'),

       Function succ ( p: POINTER TYPE ): POINTER TYPE;
   or
       Function succ ( p: POINTER TYPE; j: Integer ): POINTER TYPE;

Description
-----------

   Returns the successor of the ORDINAL TYPE value `i', or, if the
second argument `j' is given, its `j'th successor.  For integer values
`i', this is `i + 1' (or `i + j').  (No, `succ' does *not* work faster
than plain addition.  Both are optimized to a single machine
instruction or even expanded by the compiler, if possible.)

   If extended syntax is on, the argument may also be a pointer value.
In this case, the address is incremented by the size of the variable
pointed to, or, if `j' is given, by `j' times the size of the variable
pointed to.  If `p' points to an element of an array, the returned
pointer will point to the (`j'th) next element of the array.

Standards
---------

   The `succ' function is defined in ISO-7185 Standard Pascal.  The
optional second parameter is defined in ISO-10206 Extended Pascal.
Application of `succ' to pointers is defined in Borland Pascal.  The
combination of the second argument with application to pointers is a
GNU extension.

Example
-------

       Program SuccTest;
     
       Type
         Metasyntactical = ( foo, bar, baz );
     
       Var
         m: Metasyntactical;
         c: Char;
         a: array [ 1..7 ] of Integer;
         p: ^Integer;
     
       begin
         m:= succ ( foo );     (* bar *)
         c:= succ ( 'A', 4 );  (* 'E' *)
         a [ 1 ]:= 42;
         a [ 2 ]:= succ ( a [ 1 ] );     (* 43 *)
         a [ 5 ]:= succ ( a [ 2 ], 7 );  (* 50 *)
         (*$X+*)
         p:= @a [ 1 ];
         p:= succ ( p );     (* now points to `a [ 2 ]' *)
         p:= succ ( p, 3 );  (* now points to `a [ 5 ]' *)
       end.

See also
--------

   *Note pred::, *Note inc::, *Note Pointer arithmetics::.


File: gpc.info,  Node: Text,  Next: then,  Prev: succ,  Up: Reference

Text
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: then,  Next: Time,  Prev: Text,  Up: Reference

then
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Time,  Next: TimeStamp,  Prev: then,  Up: Reference

Time
====

   (Under construction.)

Syntax
------

       Function Time ( T: TimeStamp ):
           packed array [ 1..TIME LENGTH ] of Char;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: TimeStamp,  Next: to,  Prev: Time,  Up: Reference

TimeStamp
=========

   (Under construction.)

Syntax
------

       Type
         TimeStamp = record
           DateValid, TimeValid: Boolean;
           Year: Integer;
           Month: 1..12;
           Day: 1..31;
           Hour: 0..23;
           Minute, Second: 0..59;
           MicroSecond: Integer;
         end (* TimeStamp *);

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: to,  Next: to begin,  Prev: TimeStamp,  Up: Reference

to
==

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: to begin,  Next: to end,  Prev: to,  Up: Reference

to begin
========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: to end,  Next: Trim,  Prev: to begin,  Up: Reference

to end
======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Trim,  Next: true,  Prev: to end,  Up: Reference

Trim
====

   (Under construction.)

Syntax
------

       Function Trim ( S: String ): String;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: true,  Next: trunc,  Prev: Trim,  Up: Reference

true
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: trunc,  Next: Truncate,  Prev: true,  Up: Reference

trunc
=====

   (Under construction.)

Syntax
------

       Function trunc ( x: Real ): Integer;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Truncate,  Next: Type,  Prev: trunc,  Up: Reference

Truncate
========

   (Under construction.)

Syntax
------

       Procedure Truncate ( Var F: ANY FILE );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Type,  Next: TypeOf,  Prev: Truncate,  Up: Reference

Type
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: TypeOf,  Next: UnBind,  Prev: Type,  Up: Reference

TypeOf
======

Syntax
------

       Function TypeOf ( Var x ): Pointer;

Description
-----------

   Returns a pointer to the VMT of an *object* type or variable.  This
pointer can be used to identify the type of an object.

Standards
---------

   ISO Pascal does not define `TypeOf', Borland Pascal does.

Example
-------

       Type
         fooPtr = ^foo;
         barPtr = ^bar;
     
         foo = object        (* Has a VMT, though it doesn't *)
           x: Integer;       (* contain virtual methods.     *)
           Constructor Init;
         end (* foo *);
     
         bar = object ( foo )
           y: Integer;
         end (* bar *);
     
       Var
         MyFoo: fooPtr;
     
       [...]
     
       MyFoo:= New ( barPtr, Init );
     
       if TypeOf ( MyFoo^ ) = TypeOf ( bar ) then  (* true *)
         writeln ( 'OK' );

See also
--------

   *Note BitSizeOf::, *Note AlignOf::, *Note TypeOf::, *Note SetType::,
*Note OOP::.


File: gpc.info,  Node: UnBind,  Next: Unit,  Prev: TypeOf,  Up: Reference

UnBind
======

   (Under construction.)

Syntax
------

       Procedure UnBind ( Var F: ANY FILE );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Unit,  Next: unpack,  Prev: UnBind,  Up: Reference

Unit
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: unpack,  Next: until,  Prev: Unit,  Up: Reference

unpack
======

   (Under construction.)

Syntax
------

       Procedure unpack ( Source: PACKED ARRAY;
                          Var Dest: UNPACKED ARRAY;
                          FirstElement: INDEX TYPE );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: until,  Next: UpCase,  Prev: unpack,  Up: Reference

until
=====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: UpCase,  Next: update,  Prev: until,  Up: Reference

UpCase
======

   (Under construction.)

Syntax
------

       Function UpCase ( Ch: Char ): Char;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: update,  Next: uses,  Prev: UpCase,  Up: Reference

update
======

   (Under construction.)

Syntax
------

       Procedure update ( Var F: ANY FILE );
   or
       Procedure update ( Var F: ANY FILE; FileName: String );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: uses,  Next: Val,  Prev: update,  Up: Reference

uses
====

Description
-----------

   The reserved word `uses' in the *import part* of a program makes the
program import an interface.  The syntax is

       Program foo;
     
       uses
         bar1,
         bar2 in 'baz.pas',
         bar3;
     
       [...]

   or, in a Unit,

       Unit Bar3;
     
       Interface
     
       uses
         bar1,
         bar2 in 'baz.pas';
     
       [...]

   The `in' above tells GPC to look for the `Unit' in the specified
file; otherwise the file name is derived from the name of the interface
by adding first `.p', then `.pas'.

   There must be at most one import part in a program.

   In a Unit, there is only one import part in the interface part; GPC
currently does not support a second import part in the implementation
part.

   The imported interface needn't be an UCSD/Borland Pascal Unit, it
may be an interface exported by an Extended Pascal Module as well.

Standards
---------

   ISO Pascal does not define `uses' and Units in general.  UCSD and
Borland Pascal do, but without the `in' extension.  Delphi supports
`uses' like described above.

See also
--------

   *Note Unit::, *Note Module::, *Note import::.


File: gpc.info,  Node: Val,  Next: value,  Prev: uses,  Up: Reference

Val
===

   (Under construction.)

Syntax
------

       Procedure Val ( Const Source: String; Var x: INTEGER OR REAL );
   or
       Procedure Val ( Const Source: String; Var x: INTEGER OR REAL;
                       Var ErrorCode: Integer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: value,  Next: Var,  Prev: Val,  Up: Reference

value
=====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Var,  Next: virtual,  Prev: value,  Up: Reference

Var
===

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: virtual,  Next: Void,  Prev: Var,  Up: Reference

virtual
=======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Void,  Next: while,  Prev: virtual,  Up: Reference

Void
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: while,  Next: with,  Prev: Void,  Up: Reference

while
=====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: with,  Next: Word,  Prev: while,  Up: Reference

with
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Word,  Next: write,  Prev: with,  Up: Reference

Word
====

Description
-----------

   `Word' is the "natural" unsigned integer type in GNU Pascal.  On
most platforms it is 32 bits wide and thus has a range of
`0..4294967295'.  It is the same as *Note Cardinal::, introduced for
compatibility with other Pascal compilers.

   As an extension, GPC allows to use `Word' as a pseudo-schema to
produce types with a specified size in bits; for example

       Type
         Word16 = Cardinal ( 16 );

   defines an unsigned integer type with 16 bits.  The same mechanism
works for `Cardinal' and `Integer', too.

   `Word' in GNU Pascal is compatible to `unsigned int' in GNU C.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `Cardinal'.  (However see *Note Subrange
types::.)

   The `Word' type appears in Borland Pascal and Delphi, too, where it
is a 16-bit unsigned integer type.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: write,  Next: writeln,  Prev: Word,  Up: Reference

write
=====

   (Under construction.)

Syntax
------

       Procedure write ( Var F: TYPED FILE; VARIABLE );
   or
       Procedure write ( Var F: Text; VALUES AND FORMAT SPECIFICATIONS );
   or
       Procedure write ( VALUES AND FORMAT SPECIFICATIONS );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: writeln,  Next: WriteStr,  Prev: write,  Up: Reference

writeln
=======

   (Under construction.)

Syntax
------

       Procedure writeln ( Var F: Text; VALUES AND FORMAT SPECIFICATIONS );
   or
       Procedure writeln ( VALUES AND FORMAT SPECIFICATIONS );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: WriteStr,  Next: xor,  Prev: writeln,  Up: Reference

WriteStr
========

   (Under construction.)

Syntax
------

       Procedure WriteStr ( Var Dest: String; VALUES AND FORMAT SPECIFICATIONS );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: xor,  Prev: WriteStr,  Up: Reference

xor
===

Syntax
------

       Operator xor ( operand1, operand2: Boolean ) = result: Boolean;
   or
       Operator xor ( operand1, operand2: INTEGER TYPE ) = result: INTEGER TYPE;
   or
       Procedure xor ( Var operand1: INTEGER TYPE; operand2: INTEGER TYPE );

Description
-----------

   In GNU Pascal, `xor' has three built-in meanings:

  1. Logical "exclusive or" between two `Boolean'-type expressions.
     The result of the operation is of `Boolean' type.  (Logical `foo
     xor bar' in fact has the same effect as `foo <> bar'.)

  2. Bitwise "exclusive or" between two integer-type expressions.  The
     result is of the common integer type of both expressions.

  3. Use as a "procedure":  `operand1' is "xor"ed bitwise with
     `operand2'; the result is stored in `operand1'.


Standards
---------

   ISO Pascal does not define the `xor' operator; Borland Pascal and
Delphi do.

   Use of `xor' as a "procedure" is a GNU extension.

Example
-------

       Var
         a, b, c: Integer;
     
       ...
     
       if ( a = 0 ) xor ( b = 0 ) then
         c:= 1  (* happens if either `a' or `b' is zero,    *)
                (* but not if both are zero or both nonzero *)
     
       else if a xor b = 0 then  (* bitwise `xor': `a' must be the bitwise *)
         c:= 2                   (* complement of `b' to fullfill this     *)
       else
         xor ( c, a );  (* same as `c:= c xor a' *)

See also
--------

   *Note and::, *Note or::, *Note Operators::.


File: gpc.info,  Node: GPC source,  Next: Keywords,  Prev: Reference,  Up: Top

The GPC Source Reference
************************

     "The Source will be with you.  Always."

   This section tells you how to look up additional information about
the GNU Pascal compiler from its source code.  It replaces chapters
like "syntax diagrams" you probably know from the documentation of
other compilers.

   Proprietary compilers often come with a lot of technical information
about the internals of the compiler.  This is necessary because their
vendors want to avoid to distribute the source of the compiler--which
is always the most definitive source of this technical information.

   With GNU compilers, on the other hand, you are free to get the
source code, look how your compiler works internally, customize it for
your own needs, and to re-distribute it in modified or unmodified form.
You may even take money for this re-distribution.  (For details, see
the GNU General Public License, *Note Copying::.)

   The following subsections are your guide to the GNU Pascal source
code.  If you have further questions, be welcome to ask them at the GNU
Pascal mailing list (see *Note Support::).

   All file paths mentioned in this chapter are relative to the GNU
Pascal source directory, usually a subdirectory `p' of the GCC source.
For instance, `parse.y' means `/usr/local/src/gcc-2.8.1/p/parse.y' (or
whereever you have installed the GCC source on your machine);
`../tree.def' means `/usr/local/src/gcc-2.8.1/tree.def', etc.

* Menu:

* Lexical analyzer::     `gpc-lex.c'--How GPC reads your source.
* Language definition::  `parse.y'--"Syntax diagrams" as "Bison" source.
* Tree nodes::           `../tree.*'--How GPC stores your program internally.
* Parameter passing::    `gpc-typeck.c'--How GPC passes parameters.
* GPI files::            `module.c'--How GPC's precompiled Module/Unit interfaces work.
* AutoMake::             `module.c'--How GPC automatically "makes" a large project.

   (Under construction.)

   For more information, see chapters "Portability" through "Fragments"
in *Note the GCC documentation: (gcc).


File: gpc.info,  Node: Lexical analyzer,  Next: Language definition,  Up: GPC source

GPC's Lexical Analyzer
======================

   The source file `gpc-lex.c' contains the so-called *lexical
analyzer* of the GNU Pascal compiler.  (For those of you who know
`flex':  This file was *not* created using `flex' but is maintained
manually.)  This very-first stage of the compiler is responsible for
reading what you have written and dividing it into *tokens*, the
"atoms" of each computer language.  The source `gpc-lex.c' essentially
contains one large function, `yylex()'.

   Here is, for example, where the real number `3.14' and the subrange
`3..14' are distinguished, and where Borland-style character constants
like `#13' and `^M' are recognized.  This is not always a trivial task,
for example look at the following type declaration:

       Type
         X = ^Y;
         Y = packed array [ ^A..^B ] of Char;
         Z = ^A..^Z;

   If you wish to know how GPC distinguishes the pointer forward
declaration `^Y' and the subrange `^A..^Z', see `gpc-lex.c', function
`yylex()', `case '^':' in the big `switch' statement.

   There are several situation where GPC's lexical analzyer becomes
context-sensitive.  One is described above, another example is the token
`protected', a reserved word in ISO-10206 Extended Pascal, but an
ordinary identifier in ISO-7185 Standard Pascal.  It appears in
parameter lists

       Procedure foo ( protected bar: Integer );

   and says that the parameter `bar' must not be changed inside the
body of the procedure.

   OTOH, if you write a valid ISO-7185 Standard Pascal program, you can
declare a parameter `protected':

       Procedure foo ( protected, bar: Integer );

   Here both standards contradict each other.  GPC solves this problem
by checking explicitly for "protected" in the lexical analyzer:  If a
comma or a colon follows, this is an ordinary identifier, otherwise
it's a reserved word.  Having this, GPC even understands

       Procedure foo ( protected protected: Integer );

   without losing the special meaning of `protected' as a reserved word.

   The responsible code is in `gpc-lex.c'--look out for `PROTECTED'.

   If you ever encouter a bug with the lexical analyzer--now you know
where to hunt for it.


File: gpc.info,  Node: Language definition,  Next: Tree nodes,  Prev: Lexical analyzer,  Up: GPC source

Language Definition: GPC's Parser
=================================

   The file `parse.y' contains the "bison" source code of GNU Pascal's
parser.  This stage of the compilation analyzes and checks the syntax of
your Pascal program, and it generates an intermediate,
language-independent code which is then passed to the GNU back-end.

   The *bison* language essentially is a machine-readable form of the
Backus-Naur Form, the symbolic notation of grammars of computer
languages.  "Syntax diagrams" are a graphical variant of the
Backus-Naur Form.

   For details about the "bison" language, see *Note the Bison
documentation: (bison).  A short overview how to pick up some
information you might need for programming follows.

   Suppose you have forgotten how a variable is declared in Pascal.
After some searching in `parse.y' you have found the following:

       /* variable declaration part */
     
       variable_declaration_part:
                 VAR variable_declaration_list semi
               | VAR semi
                       { error ("missing variable declaration"); }
               ;
     
       variable_declaration_list:
                 variable_declaration
               | variable_declaration_list semi variable_declaration
                       { yyerrok; }
               | error
               | variable_declaration_list error variable_declaration
                       {
     		    error("missing semicolon");
                         yyerrok;
     		  }
               | variable_declaration_list semi error
               ;

   Translated into English, this means: "The variable declaration part
consists of the reserved word `Var' followed by a `variable declaration
list' and a semicolon.  A semicolon immediately following `Var' is an
error.  A `variable declaration list' in turn consists of one or more
`variable declarations', separated by semicolons." (The latter
explanation requires that you understand the recursive nature of the
definition of `variable_declaration_list'.)

   Now we can go on and search for `variable_declaration'.

       variable_declaration:
                 id_list
                       {
                         [...]
                       }
                 enable_caret ':' optional_qualifier_list type_denoter
                 absolute_or_value_specification
                       {
                         [...]
                       }
               ;

   (The `[...]' are placeholders for some C statements which aren't
important for understanding GPC's grammar.)

   From this you can look up that a variable declaration in GNU Pascal
consists of an "id list", followed by "enable_caret" (whatever that
means), a colon, an "optional qualifier list", a "type denoter", and an
"absolute or value specification".  Some of these parts are easy to
understand, the others you can look up from `parse.y'.  Remember that
the reserved word `Var' preceeds all this, and a semicolon follows all
this.

   Now you know the procedure how to get the exact grammar of the GNU
Pascal language from the source.

   The C statements, not shown above, are in some sense the most
important part of the bison source, because they are responsible for
the generation of the intermediate code of the GNU Pascal front-end,
the so-called *tree nodes*.  For instance, the C code in "type denoter"
juggles a while with variables of the type `tree', and finally returns
(assigns to `$$') a so-called *tree list* which contains the information
about the type.  The "variable declaration" gets this tree list (as the
argument `$6') and passes the type information to the C function
`declare_vars()' (declared in `util.c').  This function
`declare_vars()' does the real work of compiling a variable declaration.

   This, the parser, is the place where it becomes Pascal.


File: gpc.info,  Node: Tree nodes,  Next: Parameter passing,  Prev: Language definition,  Up: GPC source

Tree Nodes
==========

   If you want really to understand how the GNU Pascal language
front-end works internally and perhaps want to improve the compiler, it
is important that you understand GPC's internal data structures.

   The data structure used by the language front-end to hold all
information about your Pascal program are the so-called "tree nodes".
(Well, it needn't be Pascal source--tree nodes are language
independent.)  The tree nodes are kind of objects, connected to each
other via pointers.  Since the GNU compiler is written in C and was
created at a time where nobody really thought about object-orientated
programming languages yet, a lot of effort has been taken to create
these "objects" in C.

   Here is an extract from the "object hierarchy".  Omissions are marked
with "..."; nodes in parentheses are "abstract":  They are never
instantiated and aren't really defined.  They only appear here to
clarify the structure of the tree node hierarchy.  The complete list is
in `../tree.def'; additional information can be found in `../tree.h'.

       (tree_node)
       |
       |--- error_mark  (* enables GPC to continue after first error *)
       |
       |--- (identifier)
       |    |
       |    |--- identifier_node
       |    |
       |    \--- op_identifier
       |
       |--- tree_list  (* general-purpose "container object" *)
       |
       |--- tree_vec
       |
       |--- block
       |
       |--- (type)  (* information about types *)
       |    |
       |    |--- void_type
       |    |
       |    |--- integer_type
       |   ...
       |    |
       |    |--- record_type
       |    |
       |    |--- function_type
       |    |
       |    \--- lang_type  (* for language-specific extensions *)
       |
       |--- integer_cst  (* an integer constant *)
       |
       |--- real_cst
       |
       |--- string_cst
       |
       |--- complex_cst
       |
       |--- (declaration)
       |    |
       |    |--- function_decl
       |   ...
       |    |
       |    |--- type_decl
       |    |
       |    \--- var_decl
       |
       |--- (reference)
       |    |
       |    |--- component_ref
       |   ...
       |    |
       |    \--- array_ref
       |
       |--- constructor
       |
       \--- (expression)
            |
            |--- modify_expr  (* assignment *)
            |
            |--- plus_expr  (* addition *)
           ...
            |
            |--- call_expr  (* procedure/function call *)
            |
            |--- goto_expr
            |
            \--- loop_expr  (* for all loops *)

   Most of these tree nodes--struct variables in fact--contain pointers
to other tree nodes.  A `tree_list' for instance has a `tree_value' and
a `tree_purpose' slot which can contain arbitrary data; a third pointer
`tree_chain' points to the next `tree_list' node and thus allows us to
create linked lists of tree nodes.

   One example:  When GPC reads the list of identifiers in a variable
declaration

       Var
         foo, bar, baz: Integer;

   the parser creates a chain of `tree_list's whose `tree_value's hold
`identifier_node's for the identifiers `foo', `bar', and `baz'.  The
function `declare_vars()' (declared in `util.c') gets this tree list as
a parameter, does some magic, and finally passes a chain of `var_decl'
nodes to the back-end.

   The `var_decl' nodes in turn have a pointer `tree_type' which holds
a `_type' node--an `integer_type' node in the example above.  Having
this, GPC can do type-checking when a variable is referenced.

   For another example, let's look at the following statement:

       baz:= foo + bar;

   Here the parser creates a `modify_expr' tree node.  This node has two
pointers, `tree_operand[0]' which holds a representation of `baz', a
`var_decl' node, and `tree_operand[1]' which holds a representation of
the sum `foo + bar'.  The sum in turn is represented as a `plus_expr'
tree node whose `tree_operand[0]' is the `var_decl' node `foo', and
whose `tree_operand[1]' is the `var_decl' node `bar'.  Passing this
(the `modify_expr' node) to the back-end results in assembler code for
the assignment.

   If you want to have a closer look at these tree nodes, write a line
`(*$debug-tree="Foobar"*)' into your program with `FooBar' being some
identifier in your program.  (Note the capitalization of the first
character in the internal representation.)  This tells GPC to output the
`identifier_local_value' tree node--the meaning of this identifier--to
the standard error device in human-readable form.

   While hacking and debugging GPC, you will also wish to have a look
at these tree nodes in other cases.  Use the `debug_tree()' function to
do so.  (In fact `(*$debug-tree="Foobar"*)' does nothing else than to
`debug_tree()' the `identifier_local_value' of the `Foobar' identifier
node.)


File: gpc.info,  Node: Parameter passing,  Next: GPI files,  Prev: Tree nodes,  Up: GPC source

Parameter Passing
=================

   GPC supports a lot of funny things in parameter lists:  `protected'
and `const' parameters, strings with specified or unspecified length,
conformant arrays, objects as `Var' parameters, etc.  All this requires
sophisticated type-checking; the responsible function is
`convert_arguments()' in the source file `gpc-typeck.c'.  Every detail
can be looked up from there.

   Some short notes about the most interesting cases follow.

*Conformant arrays:*
     First, the array bounds are passed (an even number of parameters
     of an ordinal type), then the address of the array itself.

*Procedural parameters:*
     These need special care because a function passed as a parameter
     can be confused with a call to the function whose result is then
     passed as a parameter.  See also the functions
     `maybe_call_function()' and `probably_call_function()' in `util.c'.

*Chars:*
     According to ISO-10206 Extended Pascal, formal char parameters
     accept string values.  GPC does the necessary conversion
     implicitly.  The empty string produces a space.

*Strings and schemata:*
     Value parameter strings and schemata of known size are really
     passed by value.  Value parameter strings and schemata of unknown
     size are passed by reference, and GPC creates temporary variable
     to hold a copy of the string.

*`Const' parameters:*
     If a constant value is passed to a `Const' parameter, GPC assigns
     the value to a temporary variable whose address is passed.

*Typeless parameters:*
     These are denoted by `Var foo' or `Var foo: Void' and are
     compatible to C's `void *' parameters; the size of such entities
     is *not* passed.  Maybe we will change this in the future and pass
     the size for `Var foo' parameters whereas `Var foo: Void' will
     remain compatible to C.

*`CString' parameters:*
     GPC implicitly converts any string value such that the address of
     the actual string data is passed.  However, GPC does not
     implicitly append a `chr ( 0 )' terminator, except for string
     constants.


File: gpc.info,  Node: GPI files,  Next: AutoMake,  Prev: Parameter passing,  Up: GPC source

GPI files--GNU Pascal Interfaces
================================

   This section documents the mechanism how GPC transfers information
from the exporting Modules and Units to the Program, Module or Unit
which imports (uses) the information.

   A GPI file contains a precompiled GNU Pascal Interface.
"Precompiled" means in this context that the Interface already has been
parsed (i.e. the front-end has done its work), but that no assembler
output has been produced yet.

   The GPI file format is an implementation-dependent (but not *too*
implementation-dependent ;-) file format for storing GNU Pascal
Interfaces to be exported--Extended Pascal and PXSC module interfaces
as well as interface parts of Borland Pascal Units compiled with GNU
Pascal.

   To see what information is stored in or loaded from a GPI file, run
GPC with an additional command-line option `--debug-gpi'.  Then, GPC
will write a human-readable version of what is being stored/loaded to
the standard error device.  (See also: *Note Tree nodes::.)

   While parsing an Interface, GPC stores the names of exported objects
in tree lists--in `gpc-parse.y', the bison (yacc) source of GPC's
parser, search for `handle_autoexport'.  At the end of the Interface,
everything is stored in one or more GPI files.  This is called in
`gpc-parse.y'--search for `create_gpi_files'.  (See also: *Note
Language definition::, for an introduction to `gpc-parse.y')

   Everything else is done in gpc-module.c.  Here you can find the
source of `create_gpi_files()' which documents the file format:  First,
a header of 33 bytes containing the string `GNU Pascal Module/Unit
Interface\n' is stored, then the name of the primary source file of the
module as a string, then the name of the exported interface as a tree
node (see below), after that all exported names in the order as they
were stored while parsing.

   The names and the objects (i.e. constants, data types, variables and
functions) they refer to are internally represented as so-called *tree
nodes* as defined in the files `../tree.h' and `../tree.def' from the
GNU compiler back-end.  (See also: *Note Tree nodes::.)  The names are
stored as `identifier_node's, their meanings as
`identifier_global_value's of these nodes.  The main problem when
storing tree nodes is that they form a complicated tree in memory with
a lot of circular references making it hard to decide which information
must be stored and which mustn't.

   The functions `load_tree()' and `store_tree' load/store a tree node
with the contents of all its contained pointers in a GPI file.

   Each tree node has a `tree_code' indicating what kind of information
it contains.  Each different tree node must be stored in a different
way.  See the source of `load_tree()' and `store_tree()' for details.

   Most tree nodes contain pointers to other tree nodes; therefore
`load_tree()' and `store_tree()' are recursive functions.  The
`--debug-gpi' debugging informations contains the recursion level in
parantheses, e.g. `loaded (2):' means that the loaded information was
requested by a pointer contained in a tree node requested by a pointer
contained in a tree node representing an exported symbol.

   Since this recursion can be circular (think of a record containing a
pointer to a record of the same type), we must resolve references to
tree nodes which already have been loaded.  For this reason, all nodes
are recorded in a hash buffer--see `gpi-hash.c'.

   There are some special tree_nodes (e.g. `integer_type_node' or
`NULL_TREE') which are used very often.  They have been assigned
(normally invalid) unique `tree_code's, so they can be stored in a
single byte.

   That's it.  Now you should be able to "read" GPI files using GPC's
`--debug-gpi' option.  If you encounter a case where the loaded
information differs too much from the stored information, you have
found a bug--congratulations!  What "too much" means, depends on the
object being stored in or loaded from the GPI file.  Remind that the
order things are loaded from a GPI file is the *reversed* order things
are stored when considering *different* recursion levels, but the
*same* order when considering ths *same* recursion level.


File: gpc.info,  Node: AutoMake,  Prev: GPI files,  Up: GPC source

GPC's AutoMake Mechanism--How it Works
======================================

   When a Program/Module/Unit imports (uses) an Interface, GPC searches
for the GPI file (see *Note GPI files::) derived from the name of the
Interface.

   Case 1:  A GPI file was found.

   Each GPI file contains the name of the primary source file (normally
a `.pas' or `.p' file) of the Module/Unit, and the names of all
interfaces imported.  GPC reads this information and invokes itself
with a command like

       gpc foo.pas -M -o foo.d

   This means: preprocess the file, and write down the name of the
object file and those of all its source files in `foo.d'.  GPC reads
`foo.d' and looks if the object file exists and if the source was
modified since the creation of the object file and the gpi file.  If
so, GPC calls itself again to compile the primary source file.  When
everything is done, the `.d' file is removed.  If there was no need to
recompile, all interfaces imported by the Module/Unit are processed in
the same way as this one.

   Case 2:  No GPI file was found.

   In this case, GPC derives the name of the source file from that of
the Interface by trying first `interface.p', then `interface.pas'.
This will almost always work with Borland Pascal Units, almost never
with Extended Pascal Modules.  With Extended Pascal, compile the Module
once manually in order to produce a GPI file.

   All this is done by the function `gpi_open()' which uses some
auxiliary functions such as `module_must_be_recompiled()' and
`compile_module()'.

   Each time an object file is compiled or recognized as being
up-to-date, its name is stored in a temporary file with the same base
name as all the other temporary files used by GPC but the extension
`.gpc'.  When the top-level `gpc' is invoked (which calls `gpc1' later
on), it passes the name of this temporary file as an additional command
line parameter to `gpc1'.  After compilation has been completed, the
top-level `gpc' reads the temporary file and adds the new object files
to the arguments passed to the linker.

   The additional command `--amtmpfile' (not to be specified by the
user!) is passed to child GPC processes, so all compiles use the same
temporary file.

   The source for this is merely in `gpc-module.c', but there are also
some hacks in `gpc.c', additional command line options in
`lang-options.h' and `gpc-decl.c', and `gpc-defs.h' contains
declarations for the functions and global variables.


File: gpc.info,  Node: Keywords,  Next: Built-in,  Prev: GPC source,  Up: Top

Keywords supported by GNU Pascal
********************************

   *This chapter is outdated.  We will include it until a replacement
exists.*

   This chapter lists all keywords understood by GNU Pascal.

   By default, keywords can be redefined to make it possible that every
correct ISO 7185 program can be compiled.  However, you can use the
compiler switches `--pascal-standard', `--pascal-extended',
`--pascal-object', `--pascal-borland', and `--pascal-sc' to tell GPC
that keywords of a given standard must not to be redefined.

   The keywords are taken from the following standards:

   * ISO 7185 Standard Pascal (SP)

   * ISO 10206 Extended Pascal (EP)

   * ANSI draft Object Pascal (OP) *(not yet implemented)*

   * Borland Pascal 7.0 (BP)

   * Pascal-SC (PXSC, Pascal eXtensions for Scientific Calculations)

     Keyword         Pascal standard        Remarks
     --------------------------------------------------------------------------
     Absolute        Borland                overload variables
     Abstract        Object                 not implemented
     All             GNU                    EP "export foo = all" extension
     And             ISO Standard
     And_then        ISO Extended           short-circuit Boolean AND operator
     Array           ISO Standard
     Asm             Borland, GNU           GNU-style assembler
     Begin           ISO Standard
     Bindable        ISO Extended           external binding of files, etc.
     Case            ISO Standard
     Class           Object                 not implemented
     Const           ISO Standard
     Constructor     Object, Borland        only BP version implemented
     Destructor      Object, Borland        only BP version implemented
     Div             ISO Standard
     Do              ISO Standard
     Downto          ISO Standard
     Else            ISO Standard
     End             ISO Standard
     Export          ISO Extended           Module Interface export
     File            ISO Standard
     For             ISO Standard
     Function        ISO Standard
     Goto            ISO Standard
     If              ISO Standard
     Import          ISO Extended           Module Interface import
     Implementation  ISO Extended, Borland  Module (EP) or Unit (BP) Impl. part
     Inherited       Object, Borland        only BP version implemented
     In              ISO Standard
     Inline          Borland, GNU           only GNU inline functions implem.
     Interface       ISO Extended, Borland  Module (EP) or Unit (BP) Int. part
     Is              Object                 not implemented
     Label           ISO Standard
     Mod             ISO Standard
     Module          ISO Extended, PXSC     PXSC version only partially implem.
     Nil             ISO Standard
     Not             ISO Standard
     Object          Borland                BP 7.0 style class definition
     Of              ISO Standard
     Only            ISO Extended           import specification
     Operator        PXSC                   operator definition
     Or              ISO Standard
     Or_else         ISO Extended           short-circuit Boolean OR operator
     Otherwise       ISO Extended           default case label
     Packed          ISO Standard           does not yet pack
     Pow             ISO Extended           exponentiation op. (integer expon.)
     Procedure       ISO Standard
     Program         ISO Standard
     Property        Object                 not implemented
     Protected       ISO Extended           read-only formal parameters
     Qualified       ISO Extended           import specification
     Record          ISO Standard
     Repeat          ISO Standard
     Restricted      ISO Extended           type specification
     Set             ISO Standard
     Shl             Borland                left bit-shift operator
     Shr             Borland                right bit-shift operator
     Then            ISO Standard
     To              ISO Standard
     Type            ISO Standard
     Unit            Borland                Borland (or UCSD) style Modules
     Until           ISO Standard
     Uses            Borland                Borland (or UCSD) style import
     Value           ISO Extended           variable initializer
     Var             ISO Standard
     View            Object                 not implemented
     Virtual         Borland, Object        only Borland version implemented
     While           ISO Standard
     With            ISO Standard
     Xor             Borland                Boolean/bitwise exclusive OR op.


File: gpc.info,  Node: Built-in,  Next: Extensions,  Prev: Keywords,  Up: Top

Redefineable built-in identifiers
*********************************

   The following identifiers are built in into GNU Pascal but may be
redefined according to any supported Pascal standard.

     Maxint
     False
     True
     Input
     Output
     
     Rewrite
     Reset
     Put
     Get
     Write
     Read
     Writeln
     Readln
     Page
     New
     Dispose
     Abs
     Sqr
     Sin
     Cos
     Exp
     Ln
     Sqrt
     Arctan
     Trunc
     Round
     Pack
     Unpack
     Ord
     Chr
     Succ
     Pred
     Odd
     Eof
     Eoln

   Directives

     Asmname            Specify case-sensitive external name for Function
     C                  External name for Function shall be lowercase
     C_language         same as C
     Forward
     External           External Name of Function Has First Letter Uppercase
     Extern             same as External

   Extended Pascal required module interfaces

     Standardoutput
     Standardinput

   Object Pascal directive (not implemented)

     Override

   Extended Pascal required words

     Maxchar
     Maxreal
     Minreal
     Epsreal

   Extended Pascal required Procedures and Functions

     Gettimestamp
     Date
     Time
     Halt
     Extend
     Seekwrite
     Seekread
     Seekupdate
     Empty
     Update
     Position
     Lastposition
     Re
     Im
     Cmplx
     Card
     Arg

   Extended Pascal external binding

     Bind
     Unbind
     Binding

   Extended Pascal complex type functions

     Polar

   Extended Pascal String functions

     Readstr            Read from a string rather than a file
     Writestr           Write to a string rather than a file
     Length
     Index              Search in a string
     Substr             also `MyStr [ 1..5 ]'
     Trim
     Eq                 lexical string comparision
     Lt
     Gt
     Ne
     Le
     Ge

   Extended pascal required string schema type generator

     String

   Object pascal (not implemented)

     Copy
     Null
     Root
     Textwritable
     Self

   Borland Pascal

     GetMem             Allocate memory with given size in bytes
     FreeMem            Free memory allocated with GetMem
     Inc                Increment
     Dec                Decrement

   More exotic fruits and birds (GPC extensions)

     Static             C-sense storage class specifications
     __const__
     __external__
     __inline__
     __static__
     __volatile__
     __byte__           C-style type size modifiers
     __short__
     __long__
     __longlong__
     __unsigned__
     
     Asm                Inline assembly (GNU style)
     Alignof
     Break              C-style
     Continue
     Return
     Sizeof
     Max                for enumeral and real types
     Min
     
     Conjugate
     Mark
     Release
     
     Default            like `otherwise' in a `case' statement
     Others
     
     Close
     Definesize

   Standard Pascal data types

     Integer
     Real
     Boolean
     Char
     Text

   Extended Pascal complex type

     Complex

   GPC extensions: void type (two spellings)

     __void__
     Void

   GPC extension: C compatibility string type

     __cstring__

   Extended Pascal: TimeStamp and BindingType

     Timestamp
     Bindingtype


File: gpc.info,  Node: Extensions,  Next: Extended Pascal,  Prev: Built-in,  Up: Top

GNU Pascal extensions
*********************

Extensions to ISO-7185 Pascal language
======================================

   GPC contains a number of extensions to the ISO 7185 Pascal language.

   *This chapter is outdated.  We will include it until a replacement
exists.*

   Most of these extensions are written so that they should conform to
the international standard ISO/IEC 10206 : 1991, Information technology
- Programming Languages - Extended Pascal.

   GPC is not yet fully compliant to the requirements of the Extended
Pascal language.

   The following Extended Pascal features are implemented:
   * I/O from/to strings

   * append file open mode: `extend(File)'

   * binding of external objects (GPC supports only binding of files)

   * complex dyadic operations `+,-,/,*' and monadic `-,+'

   * complex exponentiation operators (`POW' and `**')

   * complex functions (`sqr,arctan,sqrt,exp,ln,sin,cos')

   * complex number info with `re, im' and `arg' functions

   * complex numbers constructed by `cmplx' or `polar'

   * constant expressions

   * direct access I/O

   * exponentiation operators (`POW' and `**')

   * function result variable

   * functions returning structured types

   * generalized `Succ/Pred' (`val := succ (val, 5);')

   * `gettimestamp, date, time'

   * `halt' procedure

   * initial values to type declarations and/or variable declarations

   * local variable declarations may dynamically select the type and
     size

   * `maxchar/minreal/maxreal/epsreal' values.

   * modules are partially supported (@@incomplete, see below)

   * non-decimal numbers, base from 2 through 36: `base#number'

   * pointer and component access of structured return values

   * protected parameters

   * ranges and otherwise in case statements and variant records

   * read procedure can read strings from text files

   * relaxation of rules on number & order of declarations

   * required module interfaces `StandardInput' and `StandardOutput'

   * restricted types

   * set extensions (symmetric difference(`XOR') and `CARD')

   * short circuit logical operators (`AND_THEN, OR_ELSE')

   * standard numeric input (ISO 6093)

   * string and char values are compatible

   * string catenations with "`+'"

   * string comparisons with and without padding

   * string functions (`trim,substr,index,length')

   * string schema (variable length strings)

   * string schema discriminant 'Capacity' dynamically set with NEW

   * substring variables (`str[5..7] := 'foo';')

   * type inquiry

   * underscore in identifiers

   * zero fieldwidth output

   GPC extensions *not* in Extended Pascal:
   * alphanumeric labels

   * assembler code inclusion with access to variables

   * character escapes in strings

   * close file (@@ `unbind(F)' also closes a bound file `F')

   * computed goto

   * function pointers

   * `halt' procedure may have a numeric exit status parameter

   * `mark/release'

   * optional file name in `reset/rewrite/extend' as a string

   * `return / break / continue' statements

   * simple "modules" in addition to the Extended Pascal modules.

   * `sizeof/alignof' functions

   * `string[ XX ]' works like `string(XX)' as a string schema type
     selector

   * storage qualifiers in variable declarations

   * synonyms for `otherwise': `others' and `default'

   * taking address of labels

   * taking address of objects

   * type casts

   * type qualifiers

   * module initializers can be run in user specified order

   * source file preprosessor

Extended Pascal features still missing from GPC
-----------------------------------------------

   * set member iteration (`FOR ch IN [ 'a'..'z','0'..'9' ] DO...')

   * set types with variable bounds

   * structured value constructors

   * general schema types & make `NEW' work with them

   * some features of the module interface missing

   * subrange lower bound as an expression   (this is *hard* to do with
     an LALR(1) parser in single pass!     GPC allows upper bound as an
     arbitrary expression;    lower bound must now be an identifier, a
     constant or a    variable name.)

I/O to text files:
------------------

   GPC implements "lazy" text file I/O, i.e. do a `PUT' as soon as you
can and do `GET' as late as you can.

   This should avoid most of the problems sometimes considered to be
the most stupid feature of Pascal.

   When passing a file buffer as parameter the buffer is validated when
the parameter is passed.  @@ Perhaps it would be nice to hack it to be
validated when the VAR parameter is referenced...

   When any lazy file is `RESET', the file buffer state is set to
undefined. It is validated on the first reference to it.  Now this is
also true for terminal devices.

Variable length strings in GPC:
-------------------------------

   Extended Pascal has a "type selector" feature called schema types.

   GPC does not yet implement general schema types, but the `STRING
SCHEMA' is now implemented.

   (An example of a (unimplemented) schemata would be, e.g:

     Matrix (N,M: Positive_int) = array [ 1..N, 1..M ] of integer;

   Here the `M' and `N' are discriminant identifiers.)

   A `STRING SCHEMA' is the only predefined schema type in Extended
Pascal, with one required discriminant identifier "`Capacity'".

   The string schema type, if explicitely defined, could look like:

     TYPE string(capacity) = packed array [ 1..capacity ] of char;

   Internally GPC implements `STRING SCHEMA' as follows:

   The type representing the `SCHEMA TYPE' is a `RECORD_TYPE' node,
with the following fields:

     STRING  = RECORD
         Capacity : integer;
         length   : integer;
         string   : packed array [ 1..Capacity ] of char;
       END;

   The "`Capacity'" field may be directly referenced by user,

   "`length'" is referenced by a predefined string function
`LENGTH(str)' and contains the current string length.

   "`string'" contains the chars in the string.

   The "`string'" and "`length'" fields cannot be directly referenced
by a user program.

   References to the schema discriminants are allowed, and the `WITH'
statement is also allowed, so one can say:

     var str : string (80);
     begin
        writeln (str.capacity),         (* writes 80 *)
     
        with str do
          writeln (capacity);           (* writes 80 *)
     end;

   When a new `SCHEMA_TYPE' is created, the discriminant identifier
fields need to be initialized. GPC initializes the new schema type
discriminant identifiers of every `VAR_DECL' node before it executes
any instructions of the procedure, function or program where the string
variable is declared.

   If new internal schema types are created (for conversion of
fixed-string or char type parameters to a string schema formal
parameter), the discriminant identifiers are initialized immediately.
The discriminant identifiers of `PARM_DECL' nodes are not initialized
separately, they get their values from the actual parameters.

   If a parameter is a `SCHEMA_NAME' (a schema with no discriminant
identifiers), a proto string schema is used as the type of the
parameter.

   * VAR-parameter: An actual parameter to a formal schema name must be
     of `STRING_SCHEMA' type. The type of the actual parameter is used
     instead of the proto schema for the formal parameter.

   * VALUE-parameter: An actual parameter to a schema name may be
     either a `STRING_SCHEMA' type, a fixed string type or a char type.
     If the actual parameter is a string schema type, that is used
     instead of the proto schema. If it is not a schema, a new variable
     length string `VAR_DECL' is created, the actual parameter is
     copied to the new variable and the "`capacity'" field is set to
     the length of the actual variable.

   Variable length string parameters look like:

     PROGRAM Zap (output);
     
     TYPE
        stype = string (10);
        sptr  = ^string;
     
     VAR
        str  : stype;
        str2 : string(100000);
        dstr : ^string;
        zstr : sptr;
        len  : integer value 256;
     
       (* "string" accepts any length of strings *)
       PROCEDURE foo(z: string);
     
       BEGIN
         writeln ('Capacity : ',z.capacity);
         writeln ('Length   : ',length (z));
         writeln ('Contents : ',z);
       END;
     
       (* Another way to use dynamic strings *)
       PROCEDURE bar(slen : integer);
     
       var
         lstring : string (slen);
         foostr  : type of lstring;
     
       BEGIN
         lstring := 'Hello World!';
         foo (lstring);
         foostr := 'Ent{ miksi juuri t{m{?';
         foo(foostr);
       END;
     
     BEGIN
       str   := 'KUKKUU';
       str2  := 'A longer string variable';
     
       new (dstr, 1000);     { Select the string Capacity with NEW }
       dstr^ := 'The max length of this is 1000 chars';
       new (zstr, len);
       zstr^ := 'This should fit here';
     
       foo(str);
       foo(str2);
       foo('This is a constant string');
       foo('R');             { A char parameter to string routine }
       foo('');              { An empty string }
       foo (dstr^);
       foo (zstr^);
       bar (10000);
     END. (* Zap *)

   In the above example, the required procedure `NEW' was used to
select the capacity of the strings. Procedure "`BAR'" also has a string
whose size depends of the parameter passed to it and another string
whose type will be the same than the type of the first string ("`type
of'" construct).

   All string and char types are compatible as long as the destination
string is long enough to hold the source in assignments. If the source
string is shorter than the destination, the destination is
automatically blank padded if the destination string is not of string
schema type.

String routine (mostly in library):
-----------------------------------

   `S1' and `S2' may be of string or char type.  `S' is of string type.

`WRITESTR (s, write-parameter-list)'
`READSTR (s, read-parameter-list)'
     Write to a string and read from a string.  The parameter lists are
     identical to write/read from `TEXT' files. The semantics is
     closely modeled after file I/O.

`INDEX(s1,s2)'
     If `S2' is empty, return 1 else if `S1' is empty return 0 else
     returns the position of `s2' in `s1' (an integer).

`LENGTH (s1)'
     Return the length of `S1' (an integer from `0..Capacity')

`TRIM (s1)'
     Returns a new string with spaces stripped of the end of `S'.

`SUBSTR (s1, i)'
`SUBSTR (s1, i, j)'
     If `J' is missing it is calculated as: `J := LENGTH (S1) - I + 1;'
     Return a new substring of `S1' that contains `J' characters
     starting from `I'.

`EQ (s1,s2)'
`NE (s1,s2)'
`LT (s1,s2)'
`LE (s1,s2)'
`GT (s1,s2)'
`GE (s1,s2)'
     Lexicographic comparisons of `S1' and `S2'. Returns boolean result.
     Strings are not padded with spaces.

`s1  = s2'
`s1 <> s2'
`s1  < s2'
`s1 <= s2'
`s1  > s2'
`s1 >= s2'
     Pascal string compare of `S1' and `S2'. Returns boolean result.
     Shorter string is blank padded to length of the longer one.

No name space pollution with extensions:
----------------------------------------

   In GPC you are free to re-define everything that is not a reserved
word in ISO 7185 Pascal in your program.

   All Extended Pascal additional "reserved words" may be redefined, so
you do not have to modify your code for GPC if you have an identifier
like `RESTRICTED' or `VALUE' or some such.  @@ This violates Extended
Pascal standard.

   You may also redefine words like `INTEGER' and `CHAR' if you like.

   @@ NOTE: The *only* exception to the redefinition rule currently is
the word `INLINE' (to make routines inline compiled), because I added
it in front of `PROCEDURE' or `FUNCTION'.  But I think I will change
the syntax later and make `INLINE' a directive instead of a reserved
word.

Compile time switches:
----------------------

   to get info of possible clashes of keywords and other info of your
program constructs that gpc thinks are "non-standard" use the switch
"`-pedantic'" when compiling. See the GCC info files.

   @@ I have not tested the switches like -Wall very much. If you do,
@@ give me info of error messages that don't make sense in Pascal.

   @@ As a rule, GPC implements most of the switches GCC implements,
and a couple of more that cannot currently be set.

Implemented directives:
-----------------------

`FORWARD'
     Required by pascal standard.

`EXTERNAL'
     External routine which starts with a capital letter. (e.g. calling
     external function "`foo()'" will actually call "`Foo()'")

`EXTERN'
     Same as external

`C'
     Calls external routine "`foo()'" as "`foo()'" (no capitalization
     of the first letter)

`C_LANGUAGE'
     Same as C.

`STATIC'
     Make a function static in C sense.

     PROGRAM foo;
     
     PROCEDURE gotoxy(x,y: Integer); C;
     
     BEGIN
       gotoxy(10,10); (* Call external routine "gotoxy" *)
     END.

Set operations:
---------------

   GPC supports standard Pascal set operations. In addition it supports
the extended Pascal set operation symmetric difference (`set1 >< set2')
operation (a `XOR' of the set elements).

   It also has a function that counts the elements in the set: `a :=
card (set1)'

   *NOTE*: the set operations are still under construction, e.g. the set
code does not fully work in the 64 bit Alpha machines.

Initial values to type denoters:
--------------------------------

   A type (or variable) may be initialized to a value of expression
when it is declared, as in:

     program zap;
     
     type
        int10   = integer value 10;
        footype = real;
        mytype  = char value pred('A');
        etype   = (a,b,c,d,e,f,g) value d;
     
     var
        ii  : int10;                     (* Value of ii set to 10 *)
        ch  : mytype  value pred('z');
        aa  : integer value ii+10;
        foo : footype value sqrt(aa);
        e1  : etype;                     (* value set to d *)
        e2  : etype value g;             (* value set to g *)
     
     begin
     end.

   Extended pascal requires the type initializers to be constant
expressions. GPC allows any valid expression.

   Note, however, that the expressions that affect the size of storage
allocated for objects (e.g. the length of arrays) may contain variables
only inside functions or procedures.

   GPC evaluates the initial values used for the type when an
identifier is declared for that type.  If a variable is declared with a
type-denoter that uses a type-name which already has an initial value
the latter initialization has precedence.

   @@ GPC does not know how to calculate constant values for math
functions in the runtime library at compile time, e.g.
`exp(sin(2.4567))', so you should not use these kind of expressions in
object size expressions. (Extended Pascal allows this).

Date and time routines:
-----------------------

   Predefined date and time routines:

`procedure gettimestamp(VAR t: TimeStamp);'
`function date(t: TimeStamp) : packed array [ 1..DATE_LENGTH ] of char;'
`function time(t: TimeStamp) : packed array [ 1..TIME_LENGTH ] of char;'
   `DATE_LENGTH' and `TIME_LENGTH' are implementation dependent
constants. See E.20 and E.22 in chapter IMPLEMENTATION DEPENDENT
FEATURES to find out these values for GPC.

   `GetTimeStamp(t)' fills the record T with values. If they are valid,
the boolean flags are set to TRUE.

   `TimeStamp' is a required predefined type in extended pascal
standard.  (It may be extended in an implementation.)

   The definition the type in GPC looks like:
     TimeStamp = PACKED RECORD
                          DateValid,
                          TimeValid   : Boolean;
                          Year        : Integer;
                          Month       : 1 .. 12;
                          Day         : 1 .. 31;
                          DayOfWeek   : 0 .. 6;  { 0 means Sunday }
                          Hour        : 0 .. 23;
                          Minute      : 0 .. 59;
                          Second      : 0 .. 59;
                          MicroSecond : 0 .. 999999
                        END;

   All fields except DayOfWeek and MicroSecond are required by the
standard.  (@@ Currently, in GPC, TimeStamp is not actually packed.)

   @@ NOTE: `TimeStamp' may be later extended in GPC to contain the
following fields at the end of the `TimeStamp' record:

     Dst_used   : Boolean;     (* If daylight savings are used *)
     TimeZone   : Integer;     (* Positive if WEST, in minutes *)
     Weekday    : 0..6;        (* 0 is Sunday *)
     TimerValid : Boolean;     (* Is the following timer valid *)
     us_Timer   : Integer;     (* A microsecond timer that is a 32 bit
                                  modulus of the timer returned by the
                                  system. *)

   Fields `Dst_used, TimeZone' and `WeekDay' will be valid when
`DateValid' is `TRUE'. Field `us_Timer' will be valid when `TimerValid'
is `TRUE'.

Complex type and operations:
----------------------------

   The following sample programs illustrates most of the `COMPLEX' type
operations. In addition monadic `+' and `-' are supported and dyadic
`+,-,*,/' operations.

     program complex_test(output);
     
     var
        z1,z2       : complex;
        len, angle  : real;
     
     begin
        z1 := cmplx (2,1);
        writeln;
        writeln ('Complex number Z1 is: (',re(z1):1,',',im(z1):1,')');
        writeln;
     
        z2 := conjugate(z1); { GPC extension }
        writeln ('Conjugate of Z1 is: (',re(z2):1,',',im(z2):1,')');
        writeln;
        len   := abs (z1);
        angle := arg (z1);
        writeln ('The polar representation of Z1 is LENGTH=',len:1,
                 ' ANGLE=',angle:1);
        writeln;
     
        z2    := polar (len, angle);
        writeln ('Converting (LENGTH,ANGLE) back to (X,Y) gives: (',
                  re(z2):1,',',im(z2):1,')');
        writeln;
        writeln ('The following operations operate on the complex number Z1');
        writeln;
     
        z2 := arctan (z1);
        writeln ('arctan:  R=',re(z2),', I=',im(z2));
     
        z2 := z1 ** 3.141;
        writeln ('**3.141: R=',re(z2),', I=',im(z2));
        { cos, ln, exp, sqrt and sqr exist also }
     
        z2 := sin(z1);
        writeln ('sin:     R=',re(z2),', I=',im(z2));
     
        z2 := z1 pow 8;
        writeln ('POW 8:   R=',re(z2),', I=',im(z2));
     
        z2 := z1 pow (-8);
        writeln ('POW (-8):  R=',re(z2),', I=',im(z2));
     end.

Direct access files:
--------------------

   @@ Not tested.  @@ Write a demo program.

     type
       Dfile = file [ 1 .. 100 ] of integer;
     var
       F : Dfile;
       P, N : 1..100;

   Declares a type for a file that contains 100 integers.

   The following direct access routines may be applied to a direct
access file:

`SeekRead   (F, N);        { Open file in Inspection mode, seek to record N }'
`SeekWrite  (F, N);        { Open file in Generation mode, seek to record N }'
`SeekUpdate (F, N);        { Open file in Update mode, seek to record N }'
`Update (F);               { Writes F^, position not changed. F^ kept. }'
`p := Position (F);        { Return current record number }'
`p := LastPosition (F);    { Return the last record number in file }'
   If the file is open for Inspection or Update, `GET' may be applied.
If the file is open for Generation or Update, `PUT' may be applied.

   @@ GPC acts like the file would always start at record number 0, and
subtracts/adds the lower index from the record number.  If you think
this is incorrect, let me know.

Restricted types:
-----------------

   Extended Pascal defines restricted types as:

     restricted-type = 'restricted' type-name .

   A value of a restricted type may be passed as a value parameter to a
formal parameter possessing its underlying type, or returned as the
result of a function. A variable of a restricted type may be passed as
a variable parameter to a formal parameter possessing the same type or
its underlying type. No other operations, such as accessing a component
of a restricted type value or performing arithmetic, are possible.

     program zap;
     
     type
        unres_rec =  record
                       a :  integer;
                     end;
     
        res =  restricted unres_rec;
     
     var
        r1 :  unres_rec;
        r2 :  res;
     
        i  :  restricted integer;
        k  :  integer;
     
       function zap(p : unres_rec) : res;
       var
          ures :  unres_rec;
     
       begin
          { The parameter is treated as unrestricted, even though the actual
            parameter may be a restricted object }
          ures.a := p.a;
     
          { Legal to assign a return value }
          zap := ures;
       end; { zap }
     
     begin
        r1.a := 354;
     
        { Assigning a restricted return value to a restricted object }
        { @@ Verify if this should really be allowed????? }
        r2 := zap(r1);
     
        { Passing a restricted object to unrestericted formal parameter is ok }
        r2 := zap(r2);
     
        { *** The following are illegal *** }
        r2.a := 100;     { field access }
        r1 := r2;        { := source is restricted type }
        r2 := r1;        { := target is restricted type }
        r1 := zap(r2);   { := a restricted return value to unrestricted object }
        i  := 16#ffff;   { := target is restricted type }
        k  := i + 2;     { Arithmetic with restricted type }
     end.

Extended Pascal modules:
------------------------

   @@ GPC does not yet support:

   * renaming with '`=>''

   * `QUALIFIED' interfaces

   * `PROTECTED' export variables

   * `ONLY'

   * `IMPORT' does not work semantically correct.

   * `EXPORT' does not work semantically correct.

   * exported ranges (compiler calls `abort()')

   * module parameter lists

   GPC should be able to parse full Extended Pascal module syntax.  But
all the features are not implemented yet.

   You may load one PROGRAM and several MODULEs to make up one pascal
program. A single file may contain zero or more modules and/or zero or
one programs.

   *Please NOTE*: If you have many modules in the same file, the
variable and function declarations are visible after the point they
have been declared in the implementation even if the interface does not
export them. But they do not become visible only by including the
interface to another file and separate compiling that (so you do need
to export them now).  (@@ unfortunately, currently this applies only to
variables  and functions; all other things are visible after the
interface  has been compiled whether or not you exported them.)

   The nicest way to handle the module interface in separate
compilation environment is to use the non-standard

     #include "module-interface.ph"

   feature. You can collect your module interfaces to a single
directory and include them from there by using the "`-I DIR'" switches
to specify the include file search paths to the compiler. (See the GNU
CPP manual for more info).

   There is currently no attempt to avoid name clashes of separate
compiled modules when they are linked together.  (The exported
variables and functions having the same name  in different modules will
clash!!!)

   Sample module code with separate `INTERFACE' and `IMPLEMENTATION'
parts follows:

     MODULE foobar Interface;        (* INTERFACE *)
     
       EXPORT catch22 = (footype,setfoo,getfoo);
     
       TYPE footype = integer;
     
       PROCEDURE setfoo(f: footype);
       FUNCTION  getfoo: footype;
     
     END. { module foobar interface }
     
     
     MODULE foobar Implementation;   (* IMPLEMENTATION *)
     
       IMPORT StandardInput;
              StandardOutput;
     
       VAR foo : footype;
     
       { Note: the effect is the same as the Forward directive would have:
         parameter lists and return types are not "allowed" in the declaration
         of exported routines. }
       PROCEDURE setfoo;
       BEGIN
         foo := f;
       END;
     
       FUNCTION getfoo;
       BEGIN
         getfoo := foo;
       END;
     
       TO BEGIN DO
         BEGIN
           foo := 59;
           writeln ('Just an example of a module initializer. See comment below');
         END;
     
       TO END DO
        BEGIN
          foo := 0;
          writeln ('Goodbye');
        END;
     
     END. { foobar implementation }

   Alternatively the module interface and implementation may be
combined as follows:

     MODULE foobar;                  (* ALTERNATIVE METHOD *)
     
       EXPORT catch22 = (footype,setfoo,getfoo);
     
       TYPE footype = integer;
     
       PROCEDURE setfoo(f: footype);
       FUNCTION getfoo: footype;
     
       END; { NOTE: this END is required here, even if the
              module-block below would be empty. }
     
       VAR foo : footype;
     
       PROCEDURE setfoo;
       BEGIN
         foo := f;
       END;
     
       FUNCTION getfoo;
       BEGIN
         getfoo := foo;
       END;
     
     END. { module foobar }

   Either one of the two methods may be used with:

     PROGRAM what(output);
     
     import catch22;
     
     BEGIN
       setfoo (999);
       writeln (getfoo);
     END.

   The `INTERFACE' has to be in the same file as the program/module that
uses it's exported names.  Otherwise GPC does not know anything about
it and fails to compile the file.

Somewhat simpler GPC modules are also supported:
------------------------------------------------

   *Note*: this is not supported in Extended Pascal standard.

   This is a simpler module support that does not require exports,
imports, module headers etc.

   These non-standard simple GPC modules look like (does not have an
export part, does not have a separate  module-block, does not use
import/export features.)

     MODULE foobar;
       TYPE footype = integer;
       VAR foo: footype;
     
       PROCEDURE setfoo(f: footype);
       BEGIN
         foo := f;
       END;
     
       FUNCTION getfoo: footype;
       BEGIN
         getfoo := foo;
       END;
     END.
     
     PROGRAM what(output);
     
       (* In case the module foobar is loaded from another file *)
       PROCEDURE setfoo(f: footype); External;
       FUNCTION  getfoo: footype;    External;
     
     BEGIN
       setfoo (999);
       writeln (getfoo);
     END.

Module initialization and finalization:
---------------------------------------

   `TO BEGIN DO' module initialization and `TO END DO' module
finalization constructs are supported if the GNU compiler supports
constructors and destructors in your target machine. (It always does if
you use the GNU Linker).

   If the initialization and finalizations do not work by default, but
you have the GNU Linker, use option `-fgnu-linker' when compiling the
program.

   I re-implemeted the standard I/O handling and now the input and
output can also be used from the initialization and finalization parts.

   @@ Try these, send me bug reports. These are not tested.

Binding of objects to external names:
-------------------------------------

   GPC supports the extended pascal `bind,unbind' and `binding'
operations when applied to files.

   The compiler will currently reject binding of other object type.

   GPC implements extensions to the required predefined record type
BindingType:

     UnixTimeType = LongInt;
     
     BindingType = {@@packed} record
                     Bound             : Boolean;
                     Force             : Boolean;      { Can be set to allow binding to non-writable files or directories }
                     Extensions_Valid  : Boolean;
                     Readable          : Boolean;
                     Writable          : Boolean;
                     Executable        : Boolean;
                     Existing          : Boolean;      { Binding points to an existing file }
                     Directory         : Boolean;      { Binding points to an existing directory; Existing is False then }
                     Size              : LongInt;      { Number of elements or -1 }
                     AccessTime,                       { Time of last access }
                     ModificationTime,                 { Time of last modification }
                     ChangeTime        : UnixTimeType; { Time of last change }
                     Error             : Integer;      { Unused currently }
                     CFile             : CFilePtr;     { allows binding a Pascal file to a C file }
                     Name              : String (Binding_Name_Length)
                   end;

   The fields `BOUND' and `NAME' are required by the standard. All
other fields are extensions. (@@ Currently, in GPC, BindingType is not
actually packed.)

   The meaning of the extensions to the `BindingType' record type, and
the value of `BINDING_NAME_LENGTH' is defined in this document, section
IMPLEMENTATION DEFINED FEATURES (E.14). It is a compiler constant, the
run time system accepts any length.

   The `Size' field is a latest addition to `BindingType;' I added that
because the direct access files actually require that the file is not
bigger that the definition; and `lastposition(file)' does not work
before the file is opened. The "`Size'" field can then be used to
determine the size before `open', and if the upper bound of the direct
access file is a variable one should be able to open files of any size
without violating the standard.

   The following is an example of the binding:

     program z(input,output,f);
     
     var
        f :  text;
     
     procedure bindfile (varf :  text);
     var
        b : BindingType;
     
     begin
       unbind (f);
       b := binding (f);
       repeat
         write ('Enter file name:');
         readln (b.name);
         bind (f, b);
         b := binding (f);
         if not b.bound then
           writeln ('File not bound--try again');
       until b.bound;
     end;
     
     begin
     
       bindfile (f);
     
       (* Now the file F is bound to an external file.
        *
        * You can use the implementation defined fields
        * to check if the file is Readable, Writable and
        * if it Exists. These are valid if the.Extensions_Valid
        * field is TRUE.
        *)
     end.

Function pointers:
------------------

   GPC suports also function pointers and calls through them.  This is
a non-standard feature.

     program zap(output);
     
     type
         proc_ptr = ^ procedure (integer);
     
     var
         pvar : proc_ptr;
     
     procedure write_int(i: integer);
     begin
       writeln ('Integer: ',i:1);
     end;
     
     begin
       (* PVAR points to function WRITE_IT *)
       pvar := &write_int;
     
       (* Dereferencing a function pointer calls the function *)
       pvar^(12345);
     end.

String catenation:
------------------

   GPC supports string catenation with the '`+'' operator.  All
string-types are compatible, so you may catenate any chars, fixed
length strings and variable length strings with each other.

     program scat (input, output);
     
     var
        ch          : char;
        str         : string(100);
        str2        : string(50);
        fstr        : packed array [ 1 .. 20 ] of char;
     
     begin
        ch   := '$';
        fstr := 'demo';        { padded with blanks }
        write ('Give me some chars to play with: ');
        readln (str);
        str := '^' + 'prefix:' + str + ':suffix:' + fstr + ch;
        writeln ('Len' + 'gth = ', length (str));
        writeln (str);
     end.

Type qualifiers:
----------------

   @ New feature.  @ Currently gpc runtime does not know anything about
these.  @ These may change/or get removed...

   As an extension, GPC allows you to use type qualifiers:
`__byte__'
     8 bit integer

`__short__'
     Short integer (16 bits) or real type (32 bits)

`__long__'
     Long integer or real type

`__longlong__'
     long long integer type (64 bits)

`__unsigned__'
     Unsigned INTEGER type

   The `__unsigned__' works for all integer types, also those that have
been previously declared with some other type qualifier, like
`__short__'. The other qualifiers do not accept types that have already
been modified with a type qualifier.

   The syntax to use the qualifiers:

     type-denoter > TYPE-QUALIFIER type-name

   (The metasymbol `>' means type-denoter has also other meanings)

   Most of these should be done with subranges anyway.  However,
'`__short__ real'' cannot be done like that, neither can '`__unsigned__
integer'' or '`__longlong__ integer''.

     program zap(output);
     
     type
        byte     = __byte__     integer;
        longint  = __long__     integer;
        float    = __short__    real;
        u_long   = __unsigned__ longint;
        verylong = __longlong__ integer;
     
     var
       i8  : byte;
       i16 : __short__ integer;
       foo : u_long;
       pi  : float;
       big : verylong;
     
     begin
       pi  := 3.141592654;
       i16 := 1000;
       big := MaxInt * i16;
       i8  := 127;
     
       (*
        * Hmm, does not work because constant is treated as an integer,
        * and this is too large. Need a method to specify long constants.
        *
        * What is the syntax in other Pascal compilers? Suggestions, please!
        *
     
       foo := 16#deadbeef;
     
        *)
     end.

Accessing command line arguments:
---------------------------------

   The following module accesses the command line with `ParamStr' and
`ParamCount' functions.

   These follow the Un*x semantics, so that
   * `arg[0]' == program name,

   * `arg[1] .. arg[ParamCount-1]' are the arguments.

     MODULE command_line interface;
     
     EXPORT cmdline = (Max_length, Arg_type, ParamStr, ParamCount);
     
     CONST
        Max_length = 255;     { Max length of each argument.
                                If some arg is longer, the run time system
                                traps it. }
     
     TYPE
       Arg_type = String(Max_length);
     
       FUNCTION ParamCount: Integer;
     
       FUNCTION ParamStr (arg_num: integer): Arg_type;
     END. { command_line interface }
     
     MODULE command_line implementation;
     
       { These are in the GPC runtime library }
       FUNCTION _p_paramcount : Integer; C;
       FUNCTION _p_paramstr (num: Integer; VAR str: String): Boolean; C;
     
       FUNCTION ParamCount;
       BEGIN
          ParamCount := _p_paramcount;
       END; { ParamCount }
     
       FUNCTION ParamStr;
     
       VAR
        Str       : Arg_type;
        Success     : Boolean;
     
       BEGIN
          Success := _p_paramstr (arg_num, Str);
     
          (* Should perhaps do something else on failure.
           *
           * Now it returns the empty string, which is also a valid
           * parameter.
           *)
          IF Success THEN
             ParamStr := Str
          else
             ParamStr := '';
       END; { ParamStr }
     END. { command_line implementation }
     
     
     { The program below, when compiled with the interface module and
       linked with the implementation module, accesses the command
       line arguments. }
     
     program zap (output);
     
     import cmdline;
     
     var
        counter : integer;
     
     begin
        writeln ('Program fetches command line arguments and outputs one per line');
        writeln ('Max length of each argument is ',Max_Length:1,' characters');
     
        for counter := 0 to ParamCount-1 do
           writeln ('Command line arg ',counter:1,' is "',paramstr(counter),'"');
     end.

Borland Extensions in GNU Pascal
================================

   GNU Pascal implements these Borland extensions to the ISO Pascal
language:

   * Program headline:  The `Program' headline may be omitted in TP/BP.
     If the headline is given, the parameters `Input' and `Output' are
     optional.  I modified GPC such that it warns about a missing
     program header, but warns about missing `Input' and `Output'
     parameters only if `pedantic'.

   * Units:  Extended Pascal "Modules" are not too different from TP/BP
     "Units".  The main difference is that modules do not automatically
     export everything mentioned in the interface part, but they need
     additional export clauses.  (Why?  For what does the interface part
     serve if not just to document what should be exported?)  So I im-
     plemented TP/BP "Units".  A Unit exports everything declared in the
     interface section.  The exported interface has the name of the Unit
     and is compatible with Extended Pascal Module interfaces since I
     just used the same routines.

     I got in trouble with "Interface" and "Implementation" which must
     be reserved words in order to compile a Unit.  On the other hand
     side they must remain redefinable to stay compatible to ISO 7185.
     I solved the problem by implementing a mechanism to "enable" and
     "disable" keywords.  When the identifier "Unit" or "Module" is
     read, "Interface" and "Implementation" are enabled as keywords.
     When compiling a valid ISO 7185 program, "Program" must be the
     first identifier, and "Interface" and "Implementation" are disabled
     and have no special meaning.  At the "end." of each compilation,
     everything is set back, so one project can mix ISO 7185 and 10206
     plus Borland standard.

     (By the way:  The "GNU specific" module definition is almost
     identical to the PXSC standard (see below: Operators).  With an
     additional keyword `global' which puts a declaration into an
     export interface with the name of the module, it will be the same.
     I am planning to implement this too.)

   * Protected formal parameters:  Using the same mechanism as above
     (and an additional hack in gpc-lex.c), I solved the "protected"
     problem.  All the following works now:

          Procedure Foo ( protected a, b, c: Integer );      (* 3 args *)
          Procedure Foo ( a, b, c, protected: Integer );     (* 4 args *)
          Procedure Foo ( a, b, protected, c: Integer );     (* 4 args *)
          Procedure Foo ( protected: Integer );              (* 1 arg  *)
          Procedure Foo ( Var protected: Integer );          (* 1 arg  *)
          Procedure Foo ( protected protected: Integer );    (* 1 arg  *)

     Furthermore, I implemented "Const" as an alternative to "protected"
     (according to Borland Pascal)

   * Compiler directives vs. preprocessor:  UCSD and Borland treat
     comments beginning with a '$' immediately following the opening
     `{' or `(*' as a compiler (or preprocessor) directive.  When a
     single character plus a `+' or `-' follows, this is also called a
     compiler switch, often associated with a command-line option.  All
     these directives are case-insensitive.

     For this extension, only the principle idea, not the implementation
     is related to Borland and UCSD.  It is okay (at least between
     Borland and UCSD) to have compiler-dependent compiler-switches.
     Only the include directive (*$I FileName *) is "standard" in both
     (now in three) Pascal dialects.

     Some Borland extensions are - of course not by chance - just an
     alternative notation for C preprocessor directives.  But there are
     differences:  Borland Pascal "preprocessor" definitions go into
     another name space than the program's definitions.  Therefore you
     can (*$D define *) so-called "conditionals" and check them via
     (*$ifdef *), but the program will not see these defines, so macros
     do not exist.  Since it was easier, makes no difference in most
     cases, and is in fact an extension, I left (*$define s*) visible to
     the program.  And I did not forbid to use the other C preprocessor
     directives in the Pascal style.  (Like this, there may be more than
     one in the same line ... )

     I implemented the following directives  (The examples simultane-
     ously illustrate different possible notations):

          (*$B+*)  or  {$B+}            Boolean complete evaluation
          (*$B-*)  or  {$B-}            --short-circuit
          
          (*$c+*)  or  {$c+}            --c-numbers
          
          (*$E+,L+,N+*)                 --char-escapes, --lazy-io,
                                        --nested-comments
          
          (* These switches are local and can change during one compile *)
          
          {$p+}                         --pedantic
          {$P-}                         end of --pedantic
          
          (*$I FileName *)              #include "filename.pas"
          
          {$m Hello! }                  write message "Hello!" to stderr
          
          (*$D FOO bar *)               #define FOO bar
          {$define CMULB}               #define CMULB
          
          (*$include <hello.ph> *)      #include <hello.ph>
          
                                        #ifdef FOO
          (*$ifdef FOO*) ... (*$endif*)   ...
                                        #endif
          
          (* ... and all the other C preprocessor directives ... *)

     By the way:  I implemented an option -borland-pascal symmetrically
     to -extended-pascal and -object-pascal.  But I couldn't figure out
     what they serve for since I didn't notice any difference in the
     compiler's behaviour with and without these options.  Nevertheless,
     I made -borland-pascal to switch on -nested-comments, so it has at
     least one effect :-).

   * Bit manipulations:  The TP/BP bit shift operators "shl" and "shr"
     do now exist in GPC; bitwise "and", "or", "xor", and "not" for
     integer values are allowed.  Warning is given, if "pedantic" -
     like for all non-ISO extensions.

          2#100101 and ( 1 shl 5 ) = 2#100000

     I could not restrain, but also implemented "and", "or", "xor" and
     "not" as "procedures":

          x:= 7;
          and ( x, 14 );          (* yields 6 *)
          xor ( x, 3 );           (* yields 5 *)

     (This is a feature I often missed with Borland Pascal.)

   * Increment, decrement:  The TP/BP built-in Procedures "inc" and
     "dec" do now exist in GPC.

          Var
            x: Integer;
            c: Char;
          
          inc ( i );      (* i:= i + 1; *)
          dec ( i, 7 );   (* i:= i - 7; *)
          inc ( c, 3 );   (* c:= chr ( ord ( c ) + 3 ); *)

   * Min, max:  These are a GNU extension and work for reals as well as
     for ordinal types.  Mixing of reals and integers is okay (result
     is real).

   * Memory management:  TP/BP allows dynamic memory management with
     `GetMem' and `FreeMem':

          GetMem ( MyPtr, 1024 );       FreeMem ( MyPtr, 1024 );

     GPC now supports this and also a "function-style" call to `GetMem':

          MyPtr:= GetMem ( 1024 );

     (see also: New in context of Object Orientated Programming)

     One somehow strange feature of Borland is *not* supported:  You can
     free parts of a variable with FreeMem, while the rest is still used
     and can be FreeMem'ed later by another pointer:

          Type
            Vector = array [ 0..65535 ] of Integer;
            VecPtr = ^Vector;
          
          Var
            p, q: VecPtr;
          
            ...
          
            GetMem ( p, 1024 * SizeOf ( Integer ) );
            q:= &p^ [ 512 ];
            ...
            FreeMem ( p, 512 * SizeOf ( Integer ) );
            ...
            FreeMem ( q, 512 * SizeOf ( Integer ) );

   * Hex numbers:  TP/BP hex numbers with a leading `$' are now
     supported by GPC parallel to base#number.

          $cafe = 2#1100101011111110

   * Typed constants vs. initialized variables:  TP/BP "typed constants"
     can now be used in GPC too.  Currently, they are just initialized
     variables (as in TP/BP), but they will be changed at least to read-
     only variables.  (Or at least a warning will be given when trying
     to change their values.)  I recommand to use typed constants only
     for effective constants and use Extended Pascal initialized
     variables as initialized variables.

          Const
            A: Integer = 7;
            B: array [ 1..3 ] of Char = ( 'B', 'a', 'r' );
               (* TP/BP also would also understand " = 'Bar'; ". *)
            Foo: record
              x, y: Integer;
            end (* Foo *)
              = ( x: 3; y: 4 );

     Borland and ISO style for the right-hand side are both supported.

     Once working on this, I also implemented VAX Pascal variable ini-
     tializing with `:=' (as an alternative to `value') and also with
     `=' (like in Borland "initialized variables").

     Warning: This was one of my last changes and is not yet stable.  I
     could not, for example, recover from 3 shift/reduce conflicts and 1
     reduce/reduce conflict.  This causes trouble when the type (for
     example a subrange) ends up with an expression such that the parser
     takes the `=' as a relational operator.

   * Absolute variables:  The "absolute" clause does now exist in GPC,
     but only for superposition of variables, not for giving an abso-
     lute address for variables.  (The latter application is useful only
     in the DOS platform anyway.)

          Procedure ReadVar ( Var x: Void; TypeChoice: Char );
          
          Var
            xInt: Integer absolute x;
            xChar: Char absolute x;
            xStr: String ( 80 ) absolute x;
          
          begin (* ReadVar *)
            ...
          end (* ReadVar *);

   * AsmName directive:  As a GNU extension, I implemented a new direc-
     tive `AsmName'.  While the `extern' directive capitalizes the first
     character of the declared name and the `C' directive makes every-
     thing lowercase, this directive allows the user to specify the
     assembler name as a string constant:

          Function MyFunc: Integer; AsmName 'MyPrettyFunc_';

     With this extension it is possible to access all external
     functions, for example the XT interface functions, and not only
     those written in lowercase.

     My first idea to use `external' for this purpose (to avoid name
     space pollution) conflicts with another Borland extension not yet
     implemen- ted:  In Borland Pascal, the declaration

          Procedure Foo; external 'MyLib';

     means that the procedure Foo should be imported by name ("Foo")
     from a dynamic link library "mylib.dll".

   * Open arrays:  Borland Pascal "open array" formal parameters are now
     implemented into GPC.  Within the function body, they have integer
     type index with lower bound 0.  (Conformant arrays are probably
     better but are incompatible to other languages.)

   * Address operator:  The address operator is "`@'" in TP/BP.
     Implemented into GPC as an alternative to "`&'".

   * Variant records:  Variant records may now be constructed with a
     subrange type, too.  E.g. "`case 1..3 of ...'" is allowed now.

   * Objects (classes):  The Borland Pascal Object Extensions are almost
     fully implemented into GPC.  This includes inheritance, virtual and
     non-virtual methods, constructors, destructors, pointer compati-
     bility, extended `New' syntax (with constructor call and/or as a
     "function"), extended `Dispose' syntax (with destructor call).

     The Borland "standard" is different from the ISO draft (which I
     have never seen), but it should not be too difficult now to im-
     plement that too (plus the Borland Delphi Object Extensions which
     *might* be identical to the ISO draft).

          Type
            MyParentPtr = ^MyParentObj;
            MyPtr = ^MyObj;
          
          MyParentObj = object
            ...
          end (* MyParentObj *);
          
          MyObj = object ( MyParentObj )
            a, b, c: Integer;
            Constructor Init;
            d, e: Char;    (* GNU extension: Data fields *)
            Destructor Fini; virtual;(* and methods may be mixed   *)
            Procedure Foo ( x: Integer );
            Function Bar: Char; virtual;
            (* "private" is not (yet) implemented *)
          end (* MyObj *);
          
          Var
            My: MyParentPtr;
          
          ...
          
          Constructor MyObj.Init;
          
          begin (* MyObj.Init *)
            inherited Init;
            a:= 0;
            MyParentObj.Bar;
          end (* MyObj.Init *);
          
          ...
          
          My:= New ( MyPtr, Init );
          My^.Foo ( 3 );
          Dispose ( My, Fini );
          New ( My, Init );
          with My^ do
            writeln ( Bar );

     I first tried to recycle parts of the C++ and/or ObjC frontend, but
     I gave up after a few hours.  Since I was not able to understand
     how they work, I re-invented and implemented my own Object frontend
     - the third one I noticed in the GNU compiler family.  Sorry.

   * Operators:  This extension is not from Borland but from the PXSC
     (Pascal eXtensions for Scientific Calculations) standard and allows
     redefinition of operators.  It must explicitly be enabled either by
     the compiler directive $X+ ("extended syntax") or by a command line
     option "-pascal-sc" or "-extended-syntax".

          (*$X+*)
          
          Type
            Vec3 = record
              x, y, z: Real;
            end (* Vec3 *);
          
          Var
            a, b, c: Vec3;
          
          Operator + ( u, v: Vec3 ) w: Vec3;
          
          begin (* Vec3 + Vec3 *)
            w.x:= u.x + v.x;
            w.y:= u.y + v.y;
            w.z:= u.z + v.z;
          end (* Vec3 + Vec3 *);
          
          ...
          
          c:= a + b;

     Extended Pascal would require an equal sign before the return value
     variable specification (`w' in the above example) while PXSC for-
     bids it.  Therefore I allow the equal sign to be present or not,
     both in a function declaration as well as in an operator
     declaration.


File: gpc.info,  Node: Extended Pascal,  Next: Borland Pascal,  Prev: Extensions,  Up: Top

About Pascal and Extended Pascal languages
******************************************

   Pascal is a well-known programming language and hardly needs to be
described here.  Notice, however, that some people's idea of Pascal is
affected by acquaintance with such products as Turbo Pascal which
differ from the Pascal standard and provide a lot of nonstandard
extensions (some of which are compatible with the Extended Pascal
standard).  Moreover, it is worth mentioning that the ISO Pascal
standard defines two levels of the language, level 0 and level 1; the
only difference between the levels is that level 1 supports the
so-called conformant array schemas in parameter declarations.

   Extended Pascal is a standardized language which contains so
significant extensions to Pascal that it is best regarded as a new
language.  It is currently not very well known, and computer vendors do
not seem to be eager to provide compilers for it.  Thus, there is
social need for GNU Pascal supporting Extended Pascal.

A comparison of Borland Turbo Pascal with Extended Pascal
=========================================================

   As mentioned earlier, Turbo Pascal does not conform to any of the
Pascal standards.  If you carefully chose a subset of unextended
Pascal, you may be able to port code if you're lucky/careful.

   To be fair, Turbo Pascal has some wonderful features that make it
very powerful in the environments in which it runs.  However, some of
those features are of little use on non Windows/DOS platforms and
probably are not good candidates for standardization.

   There are several Turbo Pascal features which are semantically
similar to features in unextended Pascal or Extended Pascal.  Here is a
list of mappings between Turbo Pascal features and Extended Pascal
features:

   * Case constructs

       a. Extended Pascal uses `otherwise' instead of `else'.

          *Borland Pascal*
               case c of
                 'A' : ;
                 'B' : ;
                 else ...;
               end;

          *Extended Pascal*
               case c of
                 'A' : ;
                 'B' : ;
                 otherwise ...;
               end;

       b. Missing cases cause Extended Pascal compilers to halt. In the
          case statement above if you had no `otherwise' clause and
          char c had the value 'C', you got an error (note, this would
          be unnoticed in Borland Pascal).


   * Procedure and function types and variables

     Here is an area of subtle differences.  Turbo Pascal has true
     procedure/function types but doesn't have standard Pascal's
     procedural/functional parameters.

     *Borland Pascal*
          type
            CompareFunction = function(Key1, Key2 : string) : integer;
          
          function Sort(Compare : CompareFunction);
          begin
            ...
          end;

     *Extended Pascal*
          function Sort(function Compare (Key1, Key2 : string) : integer);
          begin
            ...
          end;

     Moving from Turbo Pascal to Extended Pascal might be difficult if
     the Turbo Pascal program saves, compares, trades, etc. procedure
     values.  For example, an array of procedure values isn't possible
     in Extended Pascal.  Moving the other way is a little easier as
     shown by the above examples.

   * Strings

       a. Borland Pascal's string type has a special case, namely
          `string' without a length meaning the same as `string[255]'.
          There is no default in Extended Pascal so you have to change
          all string types to `string(255)'. Example:

               var
                 s : string;

          becomes:
               var
                 s : string(255);

          Note also that you have to use parentheses instead of
          brackets.

       b. A nice pitfall is the pointer to string as in:

               type
                 PString = ^String;

          In Extended Pascal this is a pointer to a schema type! Don't
          forget to translate this to:

               type
                 string255 = string(255);
                 PString = ^string255;

          If you indeed want to use String as a schema pointer you can
          define things like:

               type
                 MyStr : ^String;
               begin
                 New(MyStr, 1024);
               end;

          to allocate 1024 bytes of string space.

       c. As you could see above, Extended Pascal has no 255 byte limit
          for strings. It is however save to assume a limit of about
          32000 bytes. At least Prospero's Extended Pascal limits
          strings to 32760 bytes. GNU Pascal allow larger strings up to
          2G bytes.  DEC Pascal limits strings to 65535 bytes.


   * Constant variables

       a. Extended Pascal translates Borland's gruesome:

               const
                 i:integer = 0;

          to:

               var
                 i : integer value 0;

       b. You can also assign initialization values to types:

               type
                 MyInteger = integer value 0;
               
               var
                 i : MyInteger;

          All variables of type MyInteger are automatically initialized
          to 0 when created.

       c. Constant arrays of type string are translated from:

               const
                 MyStringsCount = 5;
               type
                 Ident = string[20];
               const
                 MyStrings : array [1..MyStringsCount] of Ident = (
                               'EXPORT', 'IMPLEMENTATION', 'IMPORT', 'INTERFACE',
                               'MODULE');

          to:

               const
                 MyStringsCount = 5;
               type
                 Ident = string(20);
               var
                 MyStrings : array [1..MyStringsCount] of Ident value [
                   1:'EXPORT'; 2:'IMPLEMENTATION'; 3:'IMPORT';
                   4:'INTERFACE'; 5:'MODULE'];

          There seem to be pros and cons to each style.

          Some folks don't like having to specify an index since it
          requires renumbering if you want to add a new item to the
          middle.  However, if you index by an enumerated type, you
          might be able to avoid major renumbering by hand.


   * Variant records

     The following construction is not allowed in Extended Pascal:
          type
            PersonRec = record
              Age : integer;
              case EyeColor : (Red, Green, Blue, Brown) of
                Red, Green : (Wears_Glasses : Boolean);
                Blue, Brown : (Length_of_lashes : integer);
              end;
            end;

     The variant field needs an explicit type. Code this as:

          type
            EyeColorType = (Red, Green, Blue, Brown);
            PersonRec = record
              Age : integer;
              case EyeColor : EyeColorType of
                Red, Green : (Wears_Glasses : Boolean);
                Blue, Brown : (Length_of_lashes : integer);
              end;
            end;

   * Units

       a. You can translate units almost automatically to Extended
          Pascal Modules, taking into account some differences of
          course.

          Extended Pascal does not automatically export everything named
          in a module, but you have to create seperate export clauses.

          For example translate the following unit:

               unit A;
               
               interface
               
               uses
                 B, C;
               
               procedure D;
               
               implementation
               
               procedure D;
               begin
               end;
               
               end.

          to this module:

               module A interface;
               
               export
                 A = (D);
               
               import
                 B;
                 C;
               
               procedure D;
               
               end.
               
               module A implementation;
               
               procedure D;
               begin
               end;
               
               end.

          You can have one or more export clauses and the name of an
          export clause doesn't have to be equal to the name of the
          module.

          You also see in this example how to translate the Borland
          Pascal "uses" clause to the Extended Pascal "import" clause.

       b. Borland Pascal allows you to have code in a unit that is
          executed once, at startup, to initialize things. You can
          translate this to Extended Pascal's "to begin do ..end"
          structure.

          *Borland Pascal*
               unit A;
               
               interface
               
               implementation
               
               begin
                 { do something }
               end.

          *Extended Pascal*

               module A interface;
               end.
               
               module A implementation;
               
               to begin do begin
                 { do something }
               end;
               
               end.

          Extended Pascal also has a `"to end do .... end"' so you can
          translate `Exit' handlers also.


   * Files

     Extended Pascal treats files quite differently as Borland Pascal.
     I'm not going to treat file pointers, Get and Put here, but
     instead I focus on special Extended Pascal features.

     In Borland Pascal you can read any text file as follows:

          var
            t : text;
            Line : string;
          begin
            Assign(t, 'MYTEXT.TXT');
            Reset(t);
            while not eof(t) do  begin
              readln(t, Line);
              writeln(Line);
            end;
          end;

     The `Assign' function associated the textfile `T' with the file
     `MYTEXT.TXT'.

     In Extended Pascal, files are considered entities external to your
     program. External entities, which don't need to be files, need to
     be bound to a variable your program. Any variable to which
     external entities can be bound needs to be declared bindable. So
     the variable declaration of t becomes:

          var
            t : bindable text;

     Extended Pascal has the bind function that binds a variable with
     an external entity.  Here is an Extended Pascal procedure that
     emulates the Assign procedure in Turbo Pascal.

          procedure Assign(var t : text; protected Name : string);
          var
            b : BindingType;
          begin
            unbind (t);
            b := binding (t);
            b.Name := Name;
            bind (t, b);
            b := binding (t);
          end;

     Comments: the unbind procedure unbinds a bindable variable from
     its external entity. If it is not bound, nothing happens. The
     binding function initializes b. We call binding to set some fields
     of the BindingType record. Next we set the name field to the name
     of the file. Calling bind will bind t to the external entity. If
     we now call binding again, we get the current state of t's binding
     type. We can now check for example if the bind has succeeded by:

          if not b.bound then
            { do error processing }

     Note that Prospero's Pascal defaults to creating the file if it
     does not exists! You need to use Prospero's local addition of
     setting `b.existing' to `true' to work-around this.

     I've not worked with binary files enough, so no advice yet on how
     to access them, but you access them much the same.

     As last an example of getting the size of a file.

          function FileSize(filename : String) : LongInt;
          var
            f : bindable file [0..MaxInt] of char;
            b : BindingType;
          begin
            unbind(f);
            b := binding (f);
            b.Name := filename;
            bind(f, b);
            b := binding(f);
            SeekRead(f, 0);
            if empty(f)
              then  file_size := 0
              else  file_size := LastPosition(f) + 1;
            unbind(f);
          end(*file_size*);

     Prospero's Extended Pascal has a bug in this case. Replace the
     MaxInt in the type definition of f by a sufficiently large
     integer. GNU Pascal works correct in this case.


File: gpc.info,  Node: Borland Pascal,  Next: GPC bugs,  Prev: Extended Pascal,  Up: Top

From Borland Pascal to GNU Pascal
*********************************

   This chapter is intended to be a QuickStart guide for programmers
who are familiar with Borland Pascal, version 7 for DOS protected mode.
Other versions don't differ too much but this one is the very last DOS
version Borland has published.

* Menu:

* Borland compatibility::
* IDE versus command line::
* Comments and compiler directives::
* Units; GPI files and AutoMake::
* Optimization::
* Debugging::
* GPC inline assembler::
* Objects::
* Strings::
* Typed constants::
* Bit; byte and memory manipulation::
* User-defined operators in GPC::
* Data types in BP and GPC::
* Files::
* Built-in constants::
* Built-in operators in BP and GPC::
* Built-in Procedures and Functions::
* Parameters::
* Miscellaneous::


File: gpc.info,  Node: Borland compatibility,  Next: IDE versus command line,  Up: Borland Pascal

Borland compatibility
=====================

   Unlike other free compilers, GNU Pascal is *not* intended to be 100%
Borland compatible.  GNU Pascal is part of the GNU project, so
portability between different machines is one of its primary goals.
For this reason, non-portable features of Borland Pascal will probably
not be included into GNU Pascal.  Some other differences are so minimal
that we have more important things to do than to implement them.

   However if you want to contribute to GNU Pascal by eliminating holes
in GPC's Borland compatibility, be welcome in the GNU Pascal development
team!  See *Note How to Contribute:: for details.


File: gpc.info,  Node: IDE versus command line,  Next: Comments and compiler directives,  Prev: Borland compatibility,  Up: Borland Pascal

IDE versus command line
=======================

   On the DOS platform with DJGPP, you can use the RHIDE for GNU Pascal;
check the subdirectories of your DJGPP distribution.

   Unfortunately, there is no IDE which would run on all platforms.  We
are working on it, but this will take some time.  Please be patient--or
offer your help!

   Without an IDE, the GNU Pascal Compiler, GPC, is called about like
the command-line version of the Borland Pascal Compiler, BPC.  Edit your
source file(s) with your favorite ASCII editor, then call GNU Pascal
with a command line like

       C:\GNU-PAS> gpc hello.pas -o hello.exe

on your DOS or OS/2 box or

       myhost/home/joe/gnu-pascal> gpc hello.pas -o hello

on your UNIX (or UNIX-compatible) system.  Don't omit the suffix
`.pas':  GPC is a common interface for a Pascal compiler, a C, ObjC and
C++ compiler, an assembler, a linker, and perhaps a Modula and FORTRAN
compiler.  From the extension of your source file GPC figures out which
compiler to run.

   The `-o' is a command line option which tells GPC how the executable
has to be named.  If not given, the executable will be called `a.out'
(Unix) or `a.exe' (Dos).

   Note that GPC is case-sensitive concerning file names, so it will
*not* work if you type

       C:\GNU-PAS> GPC HELLO.PAS -O HELLO.EXE

   GPC is a very quiet compiler and doesn't print anything on the
screen unless you request it or there is an error.  If you want to see
what is going on, invoke GPC with additional options:

       -Q            "don't be quiet"  (or: Quassel-Modus in German)

(with *capital* `Q'!) means that GPC prints out the names of procedures
and functions it processes, and

       --verbose

   or abbreviated

       -v

means that GPC informs you about the stages of compilation, i.e.
preprocessing, compiling, assembling, and linking.

   One example (this time for OS/2):

       [C:\GNU-Pascal] gpc --verbose -Q hello.pas

   Throughout this chapter, we will tell you about a lot of
command-line switches.  They are all invoked this way.

   After compilation, there will be an executable `hello' file in the
current directory.  (`hello.exe' with DOS and OS/2.)  Just run it and
enjoy.  If there are errors, GNU Pascal will not stop compilation after
the first one--as Borland Pascal does--but try to catch them all in one
compilation.  If you get more error messages than your screen can hold,
you can catch them in a file (e.g. `gpc.out') or pipe them to a program
like `more' in the following way:

       gpc hello.pas 2>gpc.out

   This works with OS/2 and any bash-like shell under UNIX; for DOS you
must get a replacement for `command.com' which supports this kind of
redirection, or use the `redir' utility (see also the DJGPP FAQ):

       C:\GNU-PAS> redir -eo gpc hello.pas -o hello.exe | more

   You can also use Borland's IDE for GNU Pascal on the DOS platform:
Install the GNU Pascal Compiler in the Tools menu (via Options/Tools).

       Name:       GNU Pascal
       Path:       gpc
       Arguments:  $SAVE ALL --verbose -Q $NAME($EDNAME).pas
       HotKey:     Shift+F9

   Note once more that GPC is case-sensitive, so it is important to
specify `.pas' instead of the `.PAS' Borland Pascal would append
otherwise!

   You can include more command-line arguments to GNU Pascal (e.g.
`--automake'; see below) as you will learn more about them.

   Since Borland Pascal will try to recompile your program if you use
its `run' menu function, you will need another "tool" to run your
program:

       Name:       run program
       Path:       command.com
       Arguments:  /c $NAME($EDNAME)
       HotKey:     Shift+F10


File: gpc.info,  Node: Comments and compiler directives,  Next: Units; GPI files and AutoMake,  Prev: IDE versus command line,  Up: Borland Pascal

Comments and compiler directives
================================

   According to ISO 7185 and ISO 10206 standard, GNU Pascal can
recognize comments opened with `(*' and closed with `}'.  With Borland
Pascal, both types of comments can be nested, so you will probably have
sources where passages containing comments are "commented out".  GPC's
default behavior is to allow nested comments, so you don't need to worry
about this.  However you can switch it off either by a command-line
option, or by a compiler directive:

       --no-nested-comments     {$N-}    (*$N-*)

   The $N directive also exists in BP but has another meaning.  The
same holds for most of GPC's other compiler directives (also
corresponding to command-line options in most cases):

       --short-circuit     $B+ $B-  like in Borland Pascal:
                                    $B- means short-circuit Boolean
                                    operators; $B+ complete evaluation
     
       --c-numbers         $C+ $C-  enable/disable C-style octal 0177
                                    and hexadecial 0xFF numbers
     
       --char-escapes      $E+ $E-  enable/disable C-style character
                                    escape sequences in strings
     
       --nested-comments   $N+ $N-  see above
     
       --pedantic          $P+ $P-  give/don't give portability warnings
     
                           $W+ $W-  enable/disable warnings
     
                           $X+ $X-  enable/disable extended syntax
                                    (function return value ignore,
                                    operator definitions, ``PChars'',
                                    pointer arithmetics, ...)
     
       --borland-pascal             disable or warn about GPC features
                                    not supported by Borland Pascal;
                                    do not warn about ``dangerous'' BP
                                    features
     
       {$I FileName }               include filename.pas or
                                    filename.p (make it lowercase)
     
       {$include "filename.pas"}    include (case-sensitive)
     
       {$include <filename.pas>}    the same, but don't search in
                                    current directory
     
       {$M Hello!}                  write message "Hello!" to error
                                    device during compilation
     
       {$D GNU}                     define GNU (for conditional
       {$define GNU}                compilation)
     
       -D GNU                       the same in command line
     
       {$D loop while true do}      define "loop" to be "while
                                    true do" as a macro like in C.
                                    The name of the macro is case-sensitive.
     
       {$ifdef GNU}                 conditional compilation
         ...                        (like in Borland Pascal).
       {$else}                      GPC predefines the symbol
         ...                        __GPC__ (with two leading
       {$endif}                     and trailing underscores).

   You also can use C-style preprocessor directives, e.g. `#include.',
but this is deprecated, e.g. because of possible conflicts with Borland
Pascal style `#42' character constants.

   As in Borland Pascal, `{$...}' and `(*$...*)' are equivalent.


File: gpc.info,  Node: Units; GPI files and AutoMake,  Next: Optimization,  Prev: Comments and compiler directives,  Up: Borland Pascal

Units, GPI files and AutoMake
=============================

   You can use Units in the same way as in Borland Pascal.  However,
there are some differences, problems and new features.  (Please report
the bug if something doesn't work.)

   Concerning the syntax of a Unit, you can, if you want, use Extended
Pascal syntax to specify a Unit initializer, i.e.  instead of writing

       begin
         ...
       end.

at the end of the Unit, you can get the same result with

       to begin do
         begin
           ...
         end (* to begin *);

and there also exists

       to end do
         begin
           ...
         end (* to end *);

   which specifies a finalization routine.  You can use this instead of
Borland Pascal's exit procedures, but for compatibility the included
`system' unit also provides the `ExitProc' variable.  In *Note
Extensions:: and *Note Extended Pascal::, you can find information
about Extended Pascal Modules, an alternative to Units.

   At the moment, there are no qualified identifiers, so take care
about name clashes between different Units.

   When GPC compiles a Unit, it produces two files: an `.o' object file
(compatible with other GNU compilers such as GNU C) plus a precompiled
Interface which resides in a `.gpi' file.  (See *Note GPI files:: for
GPI file internals.)

   GPC does not automatically recognize that something is a Unit and
cannot be linked; you have to tell this by a command line switch:

       -c            only compile, don't link.

   For example, to compile two units, use:

       gpc -c myunit1.pas myunit2.pas

   Of course, one of the purposes of writing Units is to compile them
separately.  However, GNU Pascal allows you to have one or more Units
in the same source file (producing only one `.o' file but separate
`.gpi' files).  You even can have a Program and Units in one and the
same source file; in this case, no `.o' file is produced at all.

   When you have all Units compiled and want to compile the Program,
specify the `.o' files in the command line:

       gpc hello.pas myunit1.o myunit2.o

   You also can specify the program and the units in one command line:

       gpc hello.pas myunit1.pas myunit2.pas

   As an alternative to manually compiling and specifying object files,
you can use GPC's AutoMake feature.  (*Warning*: This is a new feature
in GPC 2.0 and may be unstable!)  With an additional command-line
argument

       gpc --automake hello.pas

   GPC tries to behave like Borland Pascal's `make' facility and
automatically recompiles Units the source of which has been changed.
It also works if an included file has been changed.

   For more information about the AutoMake mechanism, see *Note
AutoMake::.


File: gpc.info,  Node: Optimization,  Next: Debugging,  Prev: Units; GPI files and AutoMake,  Up: Borland Pascal

Optimization
============

   GNU Pascal is a 32 bit compiler with excellent optimization
algorithms (which are identically the same as those of GNU C).  There
are three optimization levels, specified by the command line options
`-O', `-O2', and `-O3'.  (Levels up to `-O6' are worked on.)

   One example:

       Program Test;
     
       procedure Foo;
       Var
         A, B: Integer;
       begin
         A:= 3;
         B:= 4;
         writeln ( A + B );
       end;
     
       begin
         Foo
       end.

   When GNU Pascal compiles this program with optimization, it
recognizes that the argument of writeln is the constant 7--and
optimizes away the variables `A' and `B'. If the variables were global,
they would not be optimized away because they might be accessed from
other places, but the constant 7 would still be optimized.

   For more about optimization, see the GNU C documentation.


File: gpc.info,  Node: Debugging,  Next: GPC inline assembler,  Prev: Optimization,  Up: Borland Pascal

Debugging
=========

   The command line option `-g' specifies generation of debugging
information for GDB, the GNU debugger.  GDB is not as comfortable as the
Turbo Debugger, but it has the same abilities but one:  The program
being debugged is slowed down.  For more information about GDB, call it
(with `gdb') and type in the `help' command.

   GDB has one very nice feature which might even make up for the
slowing-down problematic:  When a GNU-compiled program crashes, it puts
out a `core' file.  When you say "target core core" to the GNU
debugger, it reads the core file and can tell you the address of the
crash, the contents of variables and of the stack, and so on.

   Sometimes it is nice to have a look at the assembler output of the
compiler.  When you specify the `-S' command line option, GPC produces
an `.s' file instead of an `.o' file which contains assembler source
for your program.  More about this in the next section.

   See also "Notes for debugging" in the "Bugs" chapter; see *Note GPC
bugs::.


File: gpc.info,  Node: GPC inline assembler,  Next: Objects,  Prev: Debugging,  Up: Borland Pascal

GPC inline assembler
====================

   GNU Pascal has an inline assembler, but it is quite different from
Borland's one.  I have not yet found reasonable documentation about the
use of this assembler, but I found out the following:

   The syntax is

       asm ( 'movl $12345678, %eax' );
       asm ( 'movl %eax, %edx' );

   to move the (hex) value `$12345678' to the EAX register and then to
the EDX register.  The String argument of the asm statement is passed
as a string to the assembler stage of the compilation.  The assembler
follows the AT&T, not the Intel syntax.  Note that the order of
operands is reversed with respect to the order you know from Intel
assemblers and that the size of the arguments is appended to the
mnemonic as a suffix b (byte), w (word = 2 bytes), or l (long = 4
bytes).

   You can learn about the GNU assembler syntax when compiling your
program with `-S' (see above) and looking into the resulting assembler
source.

   To access Pascal symbols from the assembler, do something like

       asm ( 'movl %%eax, %0' : : 'rm' ( MyVariable ) );

   Here, the % signs in front of the register names are doubled because
% gets some special meaning.  The 'rm' means that the operand may be in
a register or in memory.

   (More about this is in preparation.)


File: gpc.info,  Node: Objects,  Next: Strings,  Prev: GPC inline assembler,  Up: Borland Pascal

Objects
=======

   Objects in the Borland Pascal 7.0 notation are implemented into GNU
Pascal with the following differences:

   * the "private" directive does not work,

   * data fields and methods may be mixed:
            MyObj = object
              x: Integer;
              Procedure Foo; virtual;
              y: Real;
              Function Bar: Char;
            end (* MyObj *);


File: gpc.info,  Node: Strings,  Next: Typed constants,  Prev: Objects,  Up: Borland Pascal

Strings
=======

   Strings are "Schema types" in GNU Pascal which is something more
complicated than Borland-style strings.  For variables, you cannot
specify just `String' as a type like in Borland Pascal; for parameters
and pointer types you can.  There is no 255 characters length limit.
According to Extended Pascal, the maximum string length must be in
(parantheses); GNU Pascal accepts [brackets], too, however.

   For more about Strings and Schema types see *Note Extensions:: and
*Note Extended Pascal::.

   GPC supports Borland Pascal's String-handling functions and some
more (see *Note Extensions::):

       Borland Pascal       GNU Pascal
     
       Length               Length
       Pos                  Pos, Index (1)
       Str                  Str, WriteStr (1)
       Val                  Val, ReadStr
       Copy                 Copy, SubStr, MyStr [ 2 .. 7 ] (2)
       MyStr [ 0 ]:= #7;    SetLength
         -                  Trim
       =, <>, <, <=, >, >=  =, <>, <, <=, >, >=
         -                  EQ, NE, LT, LE, GT, GE
       Insert               Insert
       Delete               Delete

   (1) the order of parameters of the Borland Pascal vs. Extended Pascal
   routines is different

   (2) `SubStr' reports a runtime error if the requested substring
does not fit in the given string, `Copy' does not


File: gpc.info,  Node: Typed constants,  Next: Bit; byte and memory manipulation,  Prev: Strings,  Up: Borland Pascal

Typed constants
===============

   GNU Pascal supports Borland Pascal's "typed constants" but also
Extended Pascal's initialized variables:

       Var
         x: Integer value 7;

   or

       Var
         x: Integer = 7;

   When a typed constant is misused as an initialized variable, a
warning is given unless you specify `--borland-pascal'.

   When you initialize a record, you may omit the field names.  When you
initialize an array, you may provied indices with a `:'.  However this
additional information is ignored completely, so perhaps it's best for
the moment only to provide the values ...

   When you want a local variable to preserve its value, define it as
`static' instead of using a typed constant. Typed constants also become
static automatically for Borland Pascal compatibility, but it's better
not to rely on this "feature" in new programs.

       Procedure Foo;
     
       Var
         x: static Real;
     
       begin (* Foo *)
         (* x keeps its value between two calls to this Procedure *)
       end (* Foo *);


File: gpc.info,  Node: Bit; byte and memory manipulation,  Next: User-defined operators in GPC,  Prev: Typed constants,  Up: Borland Pascal

Bit, byte and memory manipulation
=================================

   The (non-standard) bitwise operators `shl', `shr', `and', `or',
`xor' work in GNU Pascal like in Borland Pascal.  As an extension, you
can use them as "procedures", for examples

       and ( x, $0000FFFF );

   as an alternative to

       x:= x and $0000FFFF;

   GPC accepts the Borland-specific notation `$ABCD' for hexadecimal
numbers, but you also can use Extended Pascal notation:

        2#11111111   for a binary,
        8#177        for an octal,
       16#FF         for a hexadecimal number,

   and so on up to a basis of 36.

   `Inc' and `Dec' are implemented like in Borland Pascal; `Pred' and
`Succ' are generalized according to Extended Pascal:

       a:= Succ ( a, 5 );

   `Absolute' variables work in the context of overloading with other
variables as well as in the context of specifying an absolute address,
but the latter is highly unportable and not very useful even in DOS
protected mode.

   The `Mem' and `Port' arrays don't exist in GNU Pascal.  As a
replacement for `Port', you can use routines like those provided in the
`Ports' unit.

   Borland Pascal's procedures `FillChar' and `Move' are built-in into
GNU Pascal.


File: gpc.info,  Node: User-defined operators in GPC,  Next: Data types in BP and GPC,  Prev: Bit; byte and memory manipulation,  Up: Borland Pascal

User-defined operators in GPC
=============================

   GNU Pascal allows the user to define operators according to the
Pascal-SC syntax:

       Type
         Point = record
           x, y: Real;
         end (* Point *);
     
       Operator + ( a, b: Point ) c: Point;
     
       begin (* Point + Point *)
         c.x:= a.x + b.x;
         c.y:= a.y + b.y;
       end (* Point + Point *);

   The Pascal-SC operators `+>', `+<', etc. for exact numerical
calculations are not implemented, but you can define them.  If you
write a module which really implements these operators, please send it
to us, so we can include it into the next distribution.

   (And if you know more about modules in Pascal-SC than just their
existence, please contact us as well!  We could probably easily
implement them if we knew how they look like.  Something quite close to
Pascal-SC modules already *is* implemented as "GNU specific modules".)


File: gpc.info,  Node: Data types in BP and GPC,  Next: Files,  Prev: User-defined operators in GPC,  Up: Borland Pascal

Data types in BP and GPC
========================

   * Integer types have different sizes in Borland and GNU Pascal:

            Borland Pascal          GNU Pascal     bits(1)  signed
          
            ShortInt                ByteInt          8      yes
            Integer                 ShortInt        16      yes
            LongInt                 Integer         32      yes
            Comp                    LongInt, Comp   64      yes
            Byte                    Byte             8       no
            Word                    ShortWord       16       no
              -                     Word            32       no
              -                     LongWord        64       no

     (1) The size of the GNU Pascal types may depend on the platform.
     The sizes above currently apply to most platforms, including the
     x86.

     If you care for types with exactly the same size as in Borland
     Pascal, take a look at the `System' unit and read its comments.

     You can also declare types with a specific size, and you can get
     the size of a type with `SizeOf' in bytes (like in Borland Pascal)
     or `BitSizeOf' in bits., e.g.

          type
            MyInt  = Integer (42);  { 42 bits, signed }
            MyWord = Word (2);      { 2 bits, unsigned, i.e. 0 .. 3 }
            MyCard = Cardinal (2);  { the same }
          
            HalfInt = Integer (BitSizeOf (Integer) div 2); { A signed integer type
              whose size is half as big as that of the normal Integer is regardless
              how big Integer will be on any platform the program is compiled on. }

   * Borland's Real types are supported except for the 6-bytes software
     Real; GNU's `Real' has 8 bytes and is the same as `Double'.  In
     addition there are alternative names for real types:

            Borland Pascal          GNU Pascal
          
            Single                  Single, ShortReal
            Real                      -
            Double                  Double, Real
            Extended                Extended, LongReal
            Comp                    Comp, LongInt

   * Complex numbers:  According to Extended Pascal, GNU Pascal has
     built-in complex numbers.

   * Record types: GNU Pascal by default alignes 32-bit fields on 4-byte
     addresses because this improves performance.  The record
            Type
              myRec = record
                f, o, oo: Boolean;
                Bar: Integer;
              end (* myRec *);
     has 8 bytes, not 7.  Use the `--pack-struct' option or declare the
     record as `packed' to force GPC to pack it to 7 bytes; see *Note
     Code Gen Options::.

   * In addition to Borland's procedural types, GNU Pascal has pointers
     to procedures:

              Type
                FuncPtr = ^Function ( Real ): Real;

     Furthermore, GNU Pascal supports Standard Pascal's procedural
     parameters--see below.


File: gpc.info,  Node: Files,  Next: Built-in constants,  Prev: Data types in BP and GPC,  Up: Borland Pascal

Files
=====

   * Files like in Borland Pascal, including untyped files, `BlockRead',
     `BlockWrite' and `Assign' are supported by GPC. Instead of
     `Assign', you can also use the "Bind" mechanism of Extended Pascal.


File: gpc.info,  Node: Built-in constants,  Next: Built-in operators in BP and GPC,  Prev: Files,  Up: Borland Pascal

Built-in constants
==================

   * `MaxInt', `MaxLongInt', `Pi' constants:  built-in.

   * Other built-in constants:  GNU Pascal has `MaxChar', `MaxReal',
     and `MinReal'.


File: gpc.info,  Node: Built-in operators in BP and GPC,  Next: Built-in Procedures and Functions,  Prev: Built-in constants,  Up: Borland Pascal

Built-in operators in BP and GPC
================================

   * Exponentiation:  According to Extended Pascal, GNU Pascal supports
     exponentiation operators `pow' and `**' which do not exist in
     Borland Pascal.  You can use `x pow y' for integer and `x ** y'
     for real or complex exponents; the basis may be integer, real or
     complex in both cases.

   * Address operator:  GNU Pascal accepts Borland's `@', but also `&'
     as an address operator.

   * GNU Pascal has a symmetric set difference operator `set1 >< set2'.
     For more about this, see *Note Extensions::.


File: gpc.info,  Node: Built-in Procedures and Functions,  Next: Parameters,  Prev: Built-in operators in BP and GPC,  Up: Borland Pascal

Built-in Procedures and Functions
=================================

   * `GetMem' and `FreeMem':  `GetMem' can also act as a function in
     GNU Pascal:

            p:= GetMem ( 1024 );

     The second parameter to `FreeMem' is ignored by GNU Pascal and may
     be omitted.  Memory blocks are always freed with the same size
     they were allocated with.

     Remark: Extended Pascal Schema types provide a cleaner approach to
     most of the applications of `GetMem' and `FreeMem'.

   * `Min' and `Max':  GNU Pascal has built-in `Min' and `Max'
     functions (two arguments) which work for all ordinal types
     (`Integer', `Char', ...) plus `Real'.

   * `UpCase', `High', `Low' functions:  built-in.

   * `Lo', `Hi', `Swap' functions:  not built-in, but available in the
     `System' unit.


File: gpc.info,  Node: Parameters,  Next: Miscellaneous,  Prev: Built-in Procedures and Functions,  Up: Borland Pascal

Parameters
==========

   * Untyped Var parameters can be denoted by

            Procedure Foo ( Var x );

     like in Borland Pascal.  In GNU Pascal, you can also use

            Procedure Foo ( Var x: Void );

   * GNU Pascal defines "ellipsis" parameters for variable argument
     lists,

            Procedure Foo ( a: Integer; ... );

     but does not (yet) provide a portable mechanism to access the
     additional arguments.

   * Structured function return values:  According to Extended Pascal,
     GNU Pascal allows structured function return values.

   * Open array parameters
            Procedure Foo ( a: array of Integer );
     are implemented.  However, Standard Pascal conformant array
     parameters (only partially implemented) are a "cleaner" mechanism
     to pass arrays of variable size.

   * GNU Pascal supports Standard Pascal's procedural parameters:

            Procedure DrawGraph ( Function f ( x: Real ): Real );


File: gpc.info,  Node: Miscellaneous,  Prev: Parameters,  Up: Borland Pascal

Miscellaneous
=============

   * Headlines:  According to Extended Pascal, a Program headline must
     contain the program's parameters:

              Program Foo ( Input, Output );

     In GNU Pascal, headline parameters are optional.  If the headline
     is omitted entirely, a warning is given unless you have specified
     `--borland-pascal' in the command line.

   * Case statements:  In a case statement, GNU Pascal has `otherwise'
     as an alternative to `else' (according to Extended Pascal):

            case x of
              1: writeln ( 'one' );
              2: writeln ( 'two' );
              otherwise writeln ( 'many' );
            end (* case *);

     If there are two ore more statements following `otherwise', they
     must be grouped with `begin' and `end'.

   * Char constants: Character constants like `^M' as well as `#13' are
     implemented into GNU Pascal.

   * Sets: GNU Pascal has a `Card' function for sets which counts their
     elements.

   * Inline:  GNU Pasccal allows "inline" Procedures and Functions,
     while Borland Pascal only allows machine code to be inlined:

     Borland Pascal:

            Function Max ( x, y: Integer ): Integer;
            Inline ( $58 / $59 / $3B / $C1 / $7F / $01 / $91 );

     GNU Pascal:

            Inline Function Max ( x, y: Integer ): Integer;
          
            begin (* Max *)
              if x > y then
                Max:= x
              else
                Max:= y;
            end (* Max *);

     (Actually, a more general Max is already built-in.)

     This feature is not so important as it might seem because in
     optimization level 3 (see above), GNU Pascal automatically
     "inlines" short procedures and functions.


File: gpc.info,  Node: GPC bugs,  Next: Support,  Prev: Borland Pascal,  Up: Top

Known bugs and inconveniences; how to report bugs
*************************************************

   The GNU Pascal Compiler (GPC) does not yet implement the whole ISO
10206 Extended Pascal standard, not even the whole ISO 7185 Pascal
standard.  It is only partially compatible to Borland Pascal and
implements only some isolated features from the PXSC standard.
Furthermore, there are some known bugs which will take a long time to
be fixed.  (Any help welcome!)  Please take this into account when you
consider using GPC for any purpose.

   If you encounter a bug with GPC, please check whether it is one of
the known bugs.  If not, report it to the GNU Pascal mailing list
`gpc@hut.fi'.  (But always report it if you solve the problem! ;-)

General bugs
============

   * High optimization levels do not work properly on the Alpha.  Some
     conformance tests *fail* when compiled with `-O6' flag, which
     means that the compiler generates invalid code. Don't use this
     flag in the Alpha before the problem gets fixed.  It might have
     something to do with automatic inlining, but I have not yet looked
     at this. `-O' flag should be ok.  (Also take care when using
     explicit inline functions.)

   * Run time errors are not checked in most cases.

   * For some reason the Pascal main program does not get lineno stabs,
     so it is hard to debug it with `gdb' ...

   * The set code generated in the Alpha causes runtime errors in the
     generated code.

   * There are some bugs with mathematical functions.  GPC fails, for
     example, the "Paranoia" test.

Standard Pascal
===============

   * Type checking is mostly what C does, not what Pascal requires, so
     GPC does not yet implement a strongly typed language.  Although
     correct programs compile, incorrect ones compile also.  Please
     send us such incorrect programs, so we can fix it!

Extended Pascal
===============

   * Initialized structured variables are not yet implemented.

   * Illegal substrings let crash the program rather than triggering a
     runtime error:
            str:='1234567890';
            i:=8; j:=13;
            str:=str[i..j];
     This is one case where runtime errors should be caught, but are
     not.

Borland Pascal
==============

   See also: *Note Borland Pascal::QuickStart Guide for Borland Pascal
users.

   * Strings are implemented in a completely different way.  They are
     not limited to 255 characters with the length being in position
     zero, but they are "Schema types" which is something more
     complicated.

   * Most of Borland Pascal's System Unit is not implemented, e.g.
     `move', `FillChar', `BlockRead', `BlockWrite', `Assign',
     String-related functions, ...

     *Workaround:* Some of the missing procedures and functions are
     implemented in a separate compatibility Unit.  Check the `contrib'
     subdirectory of your GPC distribution.

   * The inline assember does not understand Borland syntax.

   * There is no `private' directive for Objects yet.

   * There is no `Inline' in Borland sense.

GNU Extensions
==============

   * The Run Time System (RTS) does not know about modified types such
     as `__byte__' or `__unsigned__ Integer's or `__long__ Real's.
     Especially, you cannot `writeln' such variables.

     *Workaround:* Cast them to their basis type before `writeln', e.g.
            Type
              Extended = __long__ Real;
          
            Var
              foo: Extended;
          
            [...]
          
            writeln ( Real ( foo ) );

Inconveniences
==============

   * The GNU debugger, `gdb', does not yet understand Pascal sets,
     files or subranges.  Now `gdb' allows you to debug these things,
     even though it does not yet understand some stabs.

   * Files of integer subranges that would fit in a byte do not;
     instead they are handled as files of integer.  This is especially
     annoying with `file of 0..255'.

Notes for debugging
===================

   * Forward referencing pointers generate `dbx' style debugging symbols
     by outputting the `.stabs' as an unknown pointer and later it just
     outputs the same `.stabs' again, but this time it also tells what
     type the pointer points to.  This seems to work for `gdb'. As of
     this writing I have not checked what happens with `sdb' type
     debugging info.  It might be that the pointer is left to be a
     `(void *)' pointer, so you have to cast it in order to output the
     object the pointer points to.

     Also, we have not tried any other debugger than `gdb'.  If you do,
     please let us know what happens.

     I think that GDB does not yet support the kind of `.stabs' that
     should be used to do this correctly:

            .stabs ":tANUMBER=BNUMBER", WHATEVER

     where ANUMBER is the unknown pointer type referenced earlier, and
     the BNUMBER is the type which ANUMBER actually is.  This construct
     is not required in C.

   * When debugging, please note that the Initial Letter In Each
     Identifier Is In Upper Case And The Rest Are In Lower Case.  If
     you wish to call C-routines declare them with the "C" directive,
     as follows:

          Procedure FooBAR(i:integer);c;

     This makes the external name to be `_foobar' (replace `_' with you
     machine prefix).

          Procedure FooBAR(i:Integer); External;

     Uses external name `_Foobar'.

          Procedure FooBAR(i:Integer); AsmName 'FooBAR';

     Uses external name `_FooBAR'.

     It is done like this to reduce name clashes with `libc.a' and
     other possible libraries.

   * All visible GPC runtime system library routines are named `_p_...'.

   * The main program name is preceeded by `program_'.  For example,
     `Program FOO' yields the external name `program_Foo' for the main
     program.  This is done because ISO Standard wants to have the
     program name in a separate name space.


File: gpc.info,  Node: Support,  Next: How to Contribute,  Prev: GPC bugs,  Up: Top

Where to get support for GNU Pascal
***********************************

   GPC is free software and comes *without any warranty*.  You have not
paid to get a license to use GNU Pascal so you cannot expect to get
phone support etc. except you pay an individual or a company to provide
such a service.

   To find such an individual or company, look into the GNU Service
Directory which is a list of people who offer support and other
consulting services.  It is in the file `SERVICE' in the GNU GCC
distribution and in the GNU Emacs distribution,
`/pub/gnu/GNUinfo/SERVICE' on a GNU FTP host, and
`http://www.gnu.ai.mit.edu/prep/service.html' in the World Wide Web.
Contact the Free Software Foundation (FSF) to get a copy or to be
listed in it (see *Note Copying:: for the address).

   In addition, you can try to find support in the Internet.  The first
address is the GNU Pascal mailing list, `gpc@hut.fi'.  To join the
list, send an e-mail to `gpc-request@hut.fi'.

   You can also ask the Usenet newsgroups for help.  There is no
specialized newsgroup for GNU Pascal, so use that one which is most
appropriate for your problem.  When in doubt, we recommend
`news://comp.lang.pascal.misc'.

   *Never forget:* Everybody who is working on GNU Pascal and answering
your questions is doing that in his free time without getting any
salery for this.  Please honor our work by contributing yours.  When
somebody has solved your problems in a newsgroup watch out for other
people's problems you can help to solve.


File: gpc.info,  Node: How to Contribute,  Next: GPC notes,  Prev: Support,  Up: Top

How you can contribute to GNU Pascal
************************************

   Below you can find a list of jobs which should be done for GNU
Pascal.  In cases where somebody is already working on it, the name of
that person is written behind the job's description together with the
status of the project; e-mail addresses are given below.

   If there is already a name behind a job, this does *not* mean that
you shouldn't do that but just that you should get in contact with that
person if you would like to contribute to that field.

   Don't forget to join the GPC mailing list, `gpc@hut.fi'.  To
subscribe, write to `gpc-request@hut.fi'.

   Welcome to the GNU Pascal development team!

List of jobs
============

     Overall coordination                    Peter           works ;-)
     Coordination with GCC developers        JanJaap          ?
     Merge into GCC main distribution        JanJaap         90%
     
     ISO 7185 Standard Pascal                Juki, Peter     works
     ISO 10206 Extended Pascal               Juki, Peter     90%
     Object Pascal                            ?
     Borland Pascal 7.0                      Peter           90%
     Delphi                                  Peter           2%
     Pascal-SC                               Peter           please help!
     
     Windows 95/NT version                   JanJaap         new port started
     
     Find all bugs                            ?              please help!
     Improve the documentation               JanJaap, Peter  please help!
     
     More strict type checking               Juki, Peter     20%
     Objects: C++ code compatibility         Peter            ?
     Objects: Interfaces                     Peter           planned
     PXSC module syntax                      Peter           planned
     Procedure overloading                   Peter           planned
     
     Run time system                         Juki, JanJaap   works
     I/O error handling                       ?
     Borland compatible System               Peter, Chief    works on DJGPP, EMX
     Borland compatible DOS                  Chief
     Borland compatible CRT                  Peter           works on DJGPP, EMX
     Borland compatible Graph                Sven            works on DJGPP, Linux
     Turbo Vision compatible library         JanJaap          ?
     POSIX library (replacement for DOS)     Berend          to be ported
     NCurses Unit                            Ken              ?
     Replacement for (parts of) CRT          Peter           beta (BO5)
     Replacement for Graph                   Sven             ?
     Replacement for Graph                   Peter           planned (BO5)
     Replacement for Turbo Vision            Peter           planned (BO5)
     
     Adaption of the XWPE IDE (for UNIX)      ?
     Pascal mode for GDB, the GNU Debugger   JanJaap         planned

List of done jobs :-)
=====================

     Documentation                           JanJaap, Peter  existing ;-)
     EMX version (DOS and OS/2)              Peter           works
     DJ version (DOS)                        JanJaap         works
     Cross compilers                         JanJaap         works
     Adaption of the RHIDE                   Robert          works
     
     Automatic make                          Peter           works
     Precompiled module interfaces           Peter           works
     Compiler options to force one standard  Peter           works
     
     Installation instructions               JanJaap, Peter  done

List of contributors (in alphabetical order)
============================================

     Berend              Berend de Boer, Nederlands
                         <berend@pobox.com>
     
     Chief               Abimbola A. Olowofoyeku, Great Britain
                         <laa12@cc.keele.ac.uk>
     
     JanJaap             Jan-Jaap van der Heijden, Nederlands
                         <j.j.vanderheijden@student.utwente.nl>
     
     Juki                Jukka Virtanen, Finland
                         <jtv@hut.fi>
     
     Ken                 Kennith Linder, USA
                         <klinder@lucky.hn.com>
     
     Peter               Peter Gerwinski, Germany
                         <peter@gerwinski.de>
     
     Robert              Robert Hoehne, Germany
                         <robert.hoehne@mathematik.tu-chemnitz.de>
     
     Sven                Sven Hilscher, Germany
                         <sven@rufus.central.de>


File: gpc.info,  Node: GPC notes,  Next: PVS,  Prev: How to Contribute,  Up: Top

GPC--Gnu Pascal Random Notes
****************************

   * a bison parser for GPC

     (the parser is a ISO 7185 standard pascal parser with extensions
     (like casts, type of, address of vars, inline, return, break,
     continue, otherwise and so on...)

   * code (glue) that can be used to convert the Pascal way of defining
     things to use routines in a modified `c-decl.c'.  This mainly does
     re-ordering of the data structures. The glue lives in
     `gpc-parser.y' or in `gpc-util.c'.

   * VAR parameters for Pascal routines

     Now done with REFERENCE_TYPE. Until the REFERENCE_TYPE is
     implemented as in C++, I just get rid of this type as soon as
     possible by converting it to POINTER_TYPE in as few places as
     possible. Currently affects `gpc-parse.y', `actualparameterlist()'
     and `default_conversion()'.

   * redeclaration of standard identifiers (NOT reserved words) This
     requires a change in `tree.def' sometime in the future; currently
     I am mis-using Tiemann's FRIEND_DECL TREECODE which looks exactly
     like my KNOWNID_DECL would look like.  So maybe there is no need
     to add it at all for Pascal.

   * run time system & routines that generate calls to the rts.  The
     old one Antti Louko & I originally wrote back in -85 when I ported
     another Pascal compiler (Pax) to BSD Vax.  Pax compiler is written
     in Pascal, and it runs on Twenex and Unix. (Very good error
     reporting capabilities.) More info on request.

   * WITH statement should work properly. No information of WITH is
     currently given to the debugger.

   * variant records

     These should work. Added routine find_field() that returns a chain
     of TREE_LIST nodes and modified build_component_ref() to work as
     follows: When `gpc-parse.y' builds a variant record, it constructs
     an unnamed RECORD_TYPE containing the possible variant selector
     field and an unnamed UNION_TYPE node. `When find_field()' sees
     unnamed RECORD_TYPE or UNION_TYPE nodes implicitely propagates to
     the inner layer of the definition. It then returns the TREE_LIST
     chain of this propagation and this is modified to a series of
     build(COMPONENT_REF,...) for all propagated RECORD_TYPE nodes,
     which the rest of gcc will handle. This does NOT YET check variant
     access errors...  When thinking about it, it does not check very
     many other things either, so maybe no one will notice this :-)

   * Arrays with non-zero lower bound

     Required some changes to `expr.c.'


File: gpc.info,  Node: PVS,  Next: Set types,  Prev: GPC notes,  Up: Top

PVS Conformance Test Results
****************************

   This is a list of failed Pascal Validation Suite Conformance tests
by GPC-1.2 (GCC-2.7.2)

   Last modified: Sun Dec 10 00:58:14 1995
Run by: Juki <jtv@hut.fi>

   Number of validation suite tests run: 199 Only LEVEL-0 tests run (no
conformant arrays).

   All programs have been named as `pDDD.pas' (DDD = three digits)
Otherwise my naming convention does not mean anything.

   All tests run with and without `-g' and with/without `-O' and
with/without `-O6' Only the tests that fail are mentioned, otherwise
they all pass.

     	TEST	WHAT HAPPENS
     	----    ------------
     i486	Mach 3 (CMU UX): 	All conformance tests pass.
     
     rs-6000 Aix 3.2.5: 		All conformance tests pass.
     
     mips	Ultrix 4.3:		All conformance tests pass.
     				*** Tested with gpc 2.5.7 only
     
     alpha:	OSF 1/V3.2c:		All conformace tests pass.
     
     	Important: DO NOT USE -O switch with the alpha GPC
     		   until the problems are fixed!!!
     
     	*** With -O the following FAIL
     	*** This is ridiculous!!! They worked before...
     	p004	FAIL
     	p029	FAIL
     	p069	FAIL
     	p072	FAIL
     	p075	FAIL
     	p076	FAIL
     	p098	FAIL
     	p108	FAIL
     	p110	FAIL
     	p111	FAIL
     	p113	FAIL
     	p128	FAIL
     	p136	FAIL
     	p142	runtime error
     	p157	FAIL
     	p164	FAIL
     	p167	FAIL
     	p171	FAIL
     
     	*** But with -O6 the following are compiled incorrectly.
     	*** (i.e. they compile but produce incorrect results).
     	*** Don't use -O6 on alpha until the bugs are fixed.
     	*** These have never worked.
     	*** I have not checked the reason for these:
     	p029	FAIL
     	p095	FAIL
     	p110	FAIL
     	p111	FAIL
     	p117	Loops
     	p157	FAIL
     
     sparc	Solaris 2.3:		*** Tested with gpc 2.6.3 only
     	003	Signal 11 received by the compiler when -O (optimized)
     
     HP-PA:	HP-UX 9.03 / --with-gnu-as
     	All other tests pass, except 003:
     
     	003	Compiler: Unrecognized insn. Compiler abort().
     		(PASS with -O6)
     
     		p003.pas:262: internal error--unrecognizable insn:
     		(jump_insn 730 728 732 (set (pc)
     		        (if_then_else (gt (const_int 0)
     		                (reg:SI 259))
     		            (label_ref 766)
     		            (pc))) -1 (nil)
     		    (nil))
     		p003.pas:262: internal gcc abort
     		p003.pas did not compile
     
     		This looks more like a generic GNU compiler bug than
     		a bug in GPC code...
     
     		003 is the PVS test 6.1.1-3.


File: gpc.info,  Node: Set types,  Next: GPC index,  Prev: PVS,  Up: Top

Implementation of Set Types in GPC
**********************************

   Information of the SET_TYPE implementation in GPC.
Juki `jtv@hut.fi'
Last modified: Wed Sep 22 11:47:27 1993

   * Memory format

     `Set of T' type nodes are represented as bit vectors, one bit for
     each element. The SET_TYPE objects contain only the bits necessary
     to represent the set type PLUS the padding to align the objects to
     the nearest word boundary. Thus, there may be unused bits in front
     and after the end of otherwise contiquous bit vector that
     represents all the elements of the set.

   * Sparse sets are not implemented

     there is no concept of "sparse sets", which I thought might be
     nice for things like `[ -maxint, maxint ]' to work. Maybe someone
     implements this later, e.g. with a list of set fragments or a list
     of set elements.

   * Negative bounds for sets do not work

     Perhaps this could be done by subtracting the low bound from all
     set elements before storing them to bitvectors.  (This might cause
     complications with set constructors in expressions?)

   * Set of integer

     This is a problem currently.  It should be dynamic, but currently
     the bounds are always set to 0..255 for an unlimited integer set.

     First aid:  We implemented a switch that specifies the bounds of
     such sets. The value should be passed to `setop.c' in some
     language independend way. (Global variables :-)

   * Set operations:

     With a massive hack attack I converted all set operations to
     inline code.  It is not perfect yet, but now it passes all set
     tests I have.  Yet, the code contains unimplemented parts (see
     `setop.c').

   * List of set operations:

     CARD_EXPR:      returns the number of set elements currently in the set
                     Extended Pascal.
     
     UNION           SETC := SETA + SETB; union of the sets
     BIT_OR_EXPR
     
     DIFF            SETC := SETA - SETB; If in A, but not in B.
     BIT_ANDTC_EXPR  (and `tc_optab' has vanished from gcc-2, so this
                     will be done ``SETA and (not (SETB))'')
     
     INTERSECTION    SETC := SETA * SETB; If in A and in B
     BIT_AND_EXPR
     
     SYMDIFF         SETC := SETA >< SETB; set symmetric difference
     BIT_XOR_EXPR    (C if only in A or only in B (Boolean `XOR')
                     Extended Pascal.
     
     SEARCH_EXPR:    in a set iteration, yields each member of the set
                     in some implementation dependend order.
                     Extended Pascal (this is not yet implemented in gpc).
     
     Rest of the operands result in boolean values.
     
     =, <>           Equality comparisons
     
     <=              `LE_EXPR'
                     SETA <= SETB denotes the inclusion of SETA in SETB
     
     >=              Implemented with `LE_EXPR', like above
                     SETA >= SETB denotes the inclusion of SETB in SETA


File: gpc.info,  Node: GPC index,  Prev: Set types,  Up: Top

Index
*****

* Menu:

* -gpc-main:                             Importing from other languages.
* -lgcc, use with -nodefaultlibs:        Link Options.
* -lgcc, use with -nostdlib:             Link Options.
* -nodefaultlibs and unresolved references: Link Options.
* -nostdlib and unresolved references:   Link Options.
* abs:                                   abs.
* absolute:                              absolute.
* addr:                                  addr.
* alignment <1>:                         alignment.
* alignment:                             AlignOf.
* AlignOf:                               AlignOf.
* all:                                   all.
* Alpha OSF/1:                           Alpha OSF/1.
* AMD29K options:                        AMD29K Options.
* and:                                   and.
* and then:                              and then.
* and_then:                              and_then.
* AnsiChar:                              AnsiChar.
* append:                                append.
* arctan:                                arctan.
* arg:                                   arg.
* arguments in frame (88k):              M88K Options.
* ARM options:                           ARM Options.
* array:                                 array.
* asm:                                   asm.
* asmname <1>:                           Importing from other languages.
* asmname:                               asmname.
* assembler syntax, 88k:                 M88K Options.
* Assign:                                Assign.
* assigned:                              assigned.
* attribute:                             attribute.
* AutoMake internals:                    AutoMake.
* Bar:                                   Schemata.
* begin:                                 begin.
* binary distributions, installing:      binary distributions.
* Bind:                                  Bind.
* bindable:                              bindable.
* Binding:                               Binding.
* BindingType:                           BindingType.
* Bison parser generator:                Installation.
* bit shift overflow (88k):              M88K Options.
* bits:                                  BitSizeOf.
* BitSizeOf:                             BitSizeOf.
* BlockRead:                             BlockRead.
* BlockWrite:                            BlockWrite.
* Boolean:                               Boolean.
* break:                                 break.
* bugs in GPC:                           GPC bugs.
* Byte:                                  Byte.
* byte writes (29k):                     AMD29K Options.
* ByteBool:                              ByteBool.
* ByteCard:                              ByteCard.
* ByteInt:                               ByteInt.
* C <1>:                                 C.
* C <2>:                                 Other languages.
* C:                                     Importing from other languages.
* C language:                            Importing from other languages.
* Card:                                  Card.
* Cardinal:                              Cardinal.
* case:                                  case.
* Char:                                  Char.
* ChDir:                                 ChDir.
* chr:                                   chr.
* close:                                 close.
* cmplx:                                 cmplx.
* code generation conventions:           Code Gen Options.
* command options:                       Invoking GPC.
* Comp:                                  Comp.
* compiler version, specifying:          Target Options.
* COMPILER_PATH:                         Environment Variables.
* Complex:                               Complex.
* Concat:                                Concat.
* configuration dependent compilation notes: compilation notes.
* conformant arrays:                     Parameter passing.
* conjugate:                             conjugate.
* Const:                                 Const.
* Constructor:                           Constructor.
* continue:                              continue.
* contributors:                          Contributors.
* Convex options:                        Convex Options.
* Copy:                                  Copy.
* cos:                                   cos.
* CPLUS_INCLUDE_PATH:                    Environment Variables.
* cross compiling:                       Target Options.
* cross-compilers:                       cross-compilers.
* CString:                               CString.
* CString2String:                        CString2String.
* C_INCLUDE_PATH:                        Environment Variables.
* C_Language <1>:                        C_Language.
* C_Language:                            Importing from other languages.
* Date:                                  Date.
* debugging information options:         Debugging Options.
* debugging, 88k OCS:                    M88K Options.
* dec:                                   dec.
* default:                               default.
* DefineSize:                            DefineSize.
* Delete:                                Delete.
* dependencies for make as output:       Environment Variables.
* dependencies, make:                    Preprocessor Options.
* DEPENDENCIES_OUTPUT:                   Environment Variables.
* Destructor:                            Destructor.
* dialect options:                       Pascal Dialect Options.
* directory options:                     Directory Options.
* Dispose:                               Dispose.
* div:                                   div.
* divide instruction, 88k:               M88K Options.
* djgpp:                                 DJGPP.
* do:                                    do.
* DOS, MS- <1>:                          EMX.
* DOS, MS-:                              DJGPP.
* Double:                                Double.
* downto:                                downto.
* DW bit (29k):                          AMD29K Options.
* else:                                  else.
* empty:                                 empty.
* EMX:                                   EMX.
* end:                                   end.
* endianness:                            endianness.
* environment variables:                 Environment Variables.
* eof:                                   eof.
* eoln:                                  eoln.
* EpsReal:                               EpsReal.
* eq:                                    eq.
* erase:                                 erase.
* Exit:                                  Exit.
* exp:                                   exp.
* Export:                                Export.
* extend:                                extend.
* Extended:                              Extended.
* extern <1>:                            Importing from other languages.
* extern:                                extern.
* external <1>:                          Importing from other languages.
* external:                              external.
* false:                                 false.
* far:                                   far.
* File:                                  File.
* file name suffix:                      Overall Options.
* file names:                            Link Options.
* FileMode:                              FileMode.
* FilePos:                               FilePos.
* FileSize:                              FileSize.
* FillChar:                              FillChar.
* flush:                                 flush.
* foo <1>:                               succ.
* foo <2>:                               import.
* foo <3>:                               far.
* foo <4>:                               Code Gen Options.
* foo <5>:                               AutoMake.
* foo <6>:                               Keywords.
* foo <7>:                               Warning Options.
* foo <8>:                               Debugging Options.
* foo <9>:                               Warning Options.
* foo <10>:                              Invoking GPC.
* foo <11>:                              Miscellaneous.
* foo <12>:                              GPC bugs.
* foo <13>:                              Parameters.
* foo <14>:                              Invoking GPC.
* foo <15>:                              Objects.
* foo <16>:                              Typed constants.
* foo:                                   OOP.
* Foo:                                   Schemata.
* foo <1>:                               Units.
* foo <2>:                               Importing from other languages.
* foo <3>:                               TypeOf.
* foo <4>:                               addr.
* foo <5>:                               uses.
* foo <6>:                               Source structures.
* foo <7>:                               Link Options.
* foo <8>:                               Parameter passing.
* foo <9>:                               Optimize Options.
* foo <10>:                              Tree nodes.
* foo <11>:                              xor.
* foo <12>:                              Environment Variables.
* foo <13>:                              Lexical analyzer.
* foo <14>:                              pred.
* foo <15>:                              object.
* foo <16>:                              record.
* foo:                                   near.
* for:                                   for.
* forward:                               forward.
* frac:                                  frac.
* FreeMem:                               FreeMem.
* front-end <1>:                         Tree nodes.
* front-end:                             Language definition.
* Function:                              Function.
* functions as parameters:               Parameter passing.
* ge:                                    ge.
* Get:                                   Get.
* GetFile:                               GetFile.
* GetMem:                                GetMem.
* GetTimeStamp:                          GetTimeStamp.
* global offset table:                   Code Gen Options.
* GNU Pascal command options:            Invoking GPC.
* goto:                                  goto.
* gp-relative references (MIPS):         MIPS Options.
* GPC and other languages:               Other languages.
* GPC bugs:                              GPC bugs.
* GPC internals:                         GPC source.
* GPC source:                            GPC source.
* GPC_EXEC_PREFIX:                       Environment Variables.
* GPI files:                             GPI files.
* gprof:                                 Debugging Options.
* grammar:                               Language definition.
* grouping options:                      Invoking GPC.
* gt:                                    gt.
* Halt:                                  Halt.
* hardware models and configurations, specifying: Submodel Options.
* high:                                  high.
* HPPA Options:                          HPPA Options.
* i386 Options:                          i386 Options.
* IBM RS/6000 and PowerPC Options:       RS/6000 and PowerPC Options.
* IBM RT options:                        RT Options.
* identifying source, compiler (88k):    M88K Options.
* if:                                    if.
* Im:                                    Im.
* Implementation:                        Implementation.
* import:                                import.
* in:                                    in.
* inc:                                   inc.
* Index:                                 Index.
* inherited <1>:                         OOP.
* inherited:                             inherited.
* inline:                                inline.
* InOutRes:                              InOutRes.
* InOutResStr:                           InOutResStr.
* Input:                                 Input.
* Insert:                                Insert.
* installing binary distributions:       binary distributions.
* installing GNU Pascal:                 Installation.
* int:                                   int.
* Integer:                               Integer.
* Integer types:                         Integer types.
* integer types, "main branch":          Main branch integer types.
* integer types, "natural":              Natural integer types.
* integer types, compatibility:          Integer types and compatibility.
* integer types, specified size:         Integer types with specified size.
* integer types, summary:                Summary of integer types.
* Intel 386 Options:                     i386 Options.
* Interface:                             Interface.
* intermediate code:                     Tree nodes.
* IOresult:                              IOresult.
* kernel and user registers (29k):       AMD29K Options.
* Label:                                 Label.
* language definition:                   Language definition.
* language dialect options:              Pascal Dialect Options.
* large bit shifts (88k):                M88K Options.
* LastPosition:                          LastPosition.
* le:                                    le.
* length:                                length.
* lexical analyzer:                      Lexical analyzer.
* Libraries:                             Link Options.
* LIBRARY_PATH:                          Environment Variables.
* link options:                          Link Options.
* linking:                               Importing from other languages.
* ln:                                    ln.
* LoCase:                                LoCase.
* LongCard:                              LongCard.
* LongestCard:                           LongestCard.
* LongestInt:                            LongestInt.
* LongestReal:                           LongestReal.
* LongestWord:                           LongestWord.
* LongInt:                               LongInt.
* longjmp warnings:                      Warning Options.
* LongReal:                              LongReal.
* LongWord:                              LongWord.
* low:                                   low.
* lt:                                    lt.
* M680x0 options:                        M680x0 Options.
* M88k options:                          M88K Options.
* machine dependent options:             Submodel Options.
* magic:                                 Tree nodes.
* main program <1>:                      Importing from other languages.
* main program:                          Exporting to other languages.
* make:                                  Preprocessor Options.
* Mark:                                  Mark.
* max:                                   max.
* MaxChar:                               MaxChar.
* MaxInt:                                MaxInt.
* MaxReal:                               MaxReal.
* MedCard:                               MedCard.
* MedInt:                                MedInt.
* MedReal:                               MedReal.
* MedWord:                               MedWord.
* memory model (29k):                    AMD29K Options.
* messages, warning:                     Warning Options.
* min:                                   min.
* MinReal:                               MinReal.
* MIPS options:                          MIPS Options.
* MkDir:                                 MkDir.
* mod:                                   mod.
* Module:                                Module.
* Modules, source structure:             Modules.
* move:                                  move.
* MoveLeft:                              MoveLeft.
* MoveRight:                             MoveRight.
* MS-DOS <1>:                            DJGPP.
* MS-DOS:                                EMX.
* ne:                                    ne.
* near:                                  near.
* New <1>:                               OOP.
* New:                                   New.
* NewCString:                            NewCString.
* Nil:                                   Nil.
* not:                                   not.
* NULL:                                  NULL.
* OBJC_INCLUDE_PATH:                     Environment Variables.
* object:                                object.
* Object-orientated programming:         OOP.
* Objects:                               Exporting to other languages.
* OCS (88k):                             M88K Options.
* odd:                                   odd.
* of:                                    of.
* only:                                  only.
* OOP:                                   OOP.
* Operator:                              Operator.
* Operators:                             Operators.
* operators, built-in:                   Built-in operators.
* operators, user-defined:               User-defined operators.
* optimize options:                      Optimize Options.
* options to control warnings:           Warning Options.
* options, code generation:              Code Gen Options.
* options, debugging:                    Debugging Options.
* options, dialect:                      Pascal Dialect Options.
* options, directory search:             Directory Options.
* options, GNU Pascal command:           Invoking GPC.
* options, grouping:                     Invoking GPC.
* options, linking:                      Link Options.
* options, optimization:                 Optimize Options.
* options, order:                        Invoking GPC.
* options, preprocessor:                 Preprocessor Options.
* or:                                    or.
* or else:                               or else.
* ord:                                   ord.
* order of options:                      Invoking GPC.
* or_else:                               or_else.
* OS/2:                                  EMX.
* others:                                others.
* otherwise:                             otherwise.
* Output:                                Output.
* output file option:                    Overall Options.
* overloaded virtual fn, warning:        Warning Options.
* pack:                                  pack.
* packed:                                packed.
* page:                                  page.
* pAnsiChar:                             pAnsiChar.
* ParamCount:                            ParamCount.
* parameter passing:                     Parameter passing.
* ParamStr:                              ParamStr.
* parser:                                Language definition.
* parser generator, Bison:               Installation.
* pChar:                                 pChar.
* PIC:                                   Code Gen Options.
* Pointer:                               Pointer.
* pointer arithmetics:                   Pointer arithmetics.
* polar:                                 polar.
* pos:                                   pos.
* Position:                              Position.
* pow:                                   pow.
* pred:                                  pred.
* preprocessor options:                  Preprocessor Options.
* procedural parameters:                 Parameter passing.
* Procedure:                             Procedure.
* processor selection (29k):             AMD29K Options.
* prof:                                  Debugging Options.
* Program:                               Program.
* programming in GPC:                    Programming.
* Programs, source structure:            Programs.
* protected:                             protected.
* PtrCard:                               PtrCard.
* PtrInt:                                PtrInt.
* PtrWord:                               PtrWord.
* Put:                                   Put.
* r0-relative references (88k):          M88K Options.
* Re:                                    Re.
* read:                                  read.
* readln:                                readln.
* ReadStr:                               ReadStr.
* Real:                                  Real.
* record:                                record.
* register positions in frame (88k):     M88K Options.
* Release:                               Release.
* rename:                                rename.
* repeat:                                repeat.
* reset:                                 reset.
* restricted:                            restricted.
* Result:                                Result.
* return:                                return.
* rewrite:                               rewrite.
* RmDir:                                 RmDir.
* round:                                 round.
* RS/6000 and PowerPC Options:           RS/6000 and PowerPC Options.
* RT options:                            RT Options.
* Run time library:                      Run time library.
* run-time options:                      Code Gen Options.
* RunError:                              RunError.
* schemata:                              Schemata.
* search path:                           Directory Options.
* second include path:                   Preprocessor Options.
* Seek:                                  Seek.
* SeekRead:                              SeekRead.
* SeekUpdate:                            SeekUpdate.
* SeekWrite:                             SeekWrite.
* Self:                                  Self.
* sequential consistency on 88k:         M88K Options.
* set:                                   set.
* SetLength:                             SetLength.
* SetType:                               SetType.
* shl:                                   shl.
* ShortCard:                             ShortCard.
* ShortInt:                              ShortInt.
* ShortReal:                             ShortReal.
* ShortWord:                             ShortWord.
* shr:                                   shr.
* sin:                                   sin.
* Single:                                Single.
* SizeOf:                                SizeOf.
* smaller data references (88k):         M88K Options.
* smaller data references (MIPS):        MIPS Options.
* SmallInt:                              SmallInt.
* source structures:                     Source structures.
* SPARC options:                         SPARC Options.
* specifying compiler version and target machine: Target Options.
* specifying hardware config:            Submodel Options.
* specifying machine version:            Target Options.
* sqr:                                   sqr.
* sqrt:                                  sqrt.
* stack checks (29k):                    AMD29K Options.
* StandardError:                         StandardError.
* StandardInput:                         StandardInput.
* StandardOutput:                        StandardOutput.
* static:                                static.
* stdarg.h and RT PC:                    RT Options.
* StdErr:                                StdErr.
* storem bug (29k):                      AMD29K Options.
* Str:                                   Str.
* String:                                String.
* String2CString:                        String2CString.
* StrPCopy:                              StrPCopy.
* structure passing (88k):               M88K Options.
* submodel options:                      Submodel Options.
* subrange types:                        Subrange types.
* SubStr:                                SubStr.
* succ:                                  succ.
* suppressing warnings:                  Warning Options.
* SVr4:                                  M88K Options.
* syntax checking:                       Warning Options.
* synthesized methods, warning:          Warning Options.
* target machine, specifying:            Target Options.
* target options:                        Target Options.
* tcov:                                  Debugging Options.
* Text:                                  Text.
* then:                                  then.
* Time:                                  Time.
* TimeStamp:                             TimeStamp.
* TMPDIR:                                Environment Variables.
* to:                                    to.
* to begin:                              to begin.
* to end:                                to end.
* tree nodes:                            Tree nodes.
* Trim:                                  Trim.
* true:                                  true.
* trunc:                                 trunc.
* Truncate:                              Truncate.
* Type:                                  Type.
* type casts:                            Type casts.
* TypeOf:                                TypeOf.
* types, schema:                         Schemata.
* UnBind:                                UnBind.
* underscores, avoiding (88k):           M88K Options.
* Unit:                                  Unit.
* Units, source structure:               Units.
* unpack:                                unpack.
* unresolved references and -nodefaultlibs: Link Options.
* unresolved references and -nostdlib:   Link Options.
* until:                                 until.
* UpCase:                                UpCase.
* update:                                update.
* uses:                                  uses.
* Val:                                   Val.
* value:                                 value.
* Var:                                   Var.
* varargs.h and RT PC:                   RT Options.
* VAX options:                           VAX Options.
* virtual:                               virtual.
* VMT:                                   Exporting to other languages.
* Void:                                  Void.
* warning for overloaded virtual fn:     Warning Options.
* warning for synthesized methods:       Warning Options.
* warning messages:                      Warning Options.
* while:                                 while.
* Windows 95:                            Windows 95/NT.
* Windows NT:                            Windows 95/NT.
* with:                                  with.
* Word:                                  Word.
* write:                                 write.
* writeln:                               writeln.
* WriteStr:                              WriteStr.
* xor:                                   xor.
* zero division on 88k:                  M88K Options.



Tag Table:
Node: Top1273
Node: Welcome3391
Node: Copying6853
Node: Funding26034
Node: Look and Feel28526
Node: Manifesto35890
Node: Contributors61925
Node: Installation67711
Node: compilation notes75013
Node: Alpha OSF/175451
Node: DJGPP76331
Node: EMX76954
Node: Windows 95/NT79674
Node: cross-compilers80560
Node: Steps of Cross82388
Node: Configure Cross83510
Node: Build Cross84594
Node: Crossbuilding86265
Node: binary distributions88301
Node: Invoking GPC89401
Node: Option Summary93306
Node: Overall Options103721
Node: Pascal Dialect Options108617
Node: Code Gen Options111972
Node: Warning Options120428
Node: Debugging Options133385
Node: Optimize Options143177
Node: Preprocessor Options153518
Node: Assembler Options160060
Node: Link Options160427
Node: Directory Options165498
Node: Target Options168990
Node: Submodel Options172688
Node: M680x0 Options174074
Node: VAX Options177583
Node: SPARC Options178118
Node: Convex Options184550
Node: AMD29K Options186731
Node: ARM Options189766
Node: M88K Options191183
Node: RS/6000 and PowerPC Options199171
Node: RT Options210167
Node: MIPS Options211871
Node: i386 Options219511
Node: HPPA Options224906
Node: Intel 960 Options228005
Node: DEC Alpha Options230615
Node: Clipper Options232287
Node: H8/300 Options232686
Node: System V Options233131
Node: Environment Variables233817
Node: Programming238065
Node: Source structures239389
Node: Programs240395
Node: Units241566
Node: Modules243407
Node: Data types243703
Node: Integer types244078
Node: Natural integer types244842
Node: Main branch integer types245746
Node: Integer types with specified size247352
Node: Integer types and compatibility248366
Node: Summary of integer types249902
Node: Subrange types252119
Node: endianness252994
Node: alignment253138
Node: Operators253257
Node: Built-in operators253589
Node: User-defined operators254276
Node: Schemata256084
Node: Pointer arithmetics257963
Node: Type casts259121
Node: OOP266843
Node: Other languages270172
Node: Importing from other languages271056
Node: Exporting to other languages273856
Node: Run time library276435
Node: Reference331196
Node: abs334642
Node: absolute336016
Node: addr338821
Node: AlignOf339175
Node: all340000
Node: and340575
Node: and then343224
Node: and_then343773
Node: AnsiChar345910
Node: append346654
Node: arctan347076
Node: arg347818
Node: array348591
Node: asm348799
Node: asmname349007
Node: Assign349224
Node: assigned349610
Node: attribute349997
Node: begin350224
Node: Bind350439
Node: bindable350711
Node: Binding350933
Node: BindingType351215
Node: BitSizeOf352780
Node: BlockRead353799
Node: BlockWrite354239
Node: Boolean354689
Node: break354912
Node: Byte355125
Node: ByteBool355876
Node: ByteCard356099
Node: ByteInt356734
Node: C357446
Node: C_Language357653
Node: Card357875
Node: Cardinal358139
Node: case359258
Node: Char359469
Node: ChDir359677
Node: chr359933
Node: close360190
Node: cmplx360445
Node: Comp360723
Node: Complex361470
Node: Concat361688
Node: conjugate362039
Node: Const362316
Node: Constructor362538
Node: continue362771
Node: Copy362997
Node: cos364569
Node: CString364867
Node: CString2String365092
Node: Date365388
Node: dec365696
Node: default366019
Node: DefineSize366240
Node: Delete366538
Node: Destructor366834
Node: Dispose367064
Node: div367459
Node: do367717
Node: Double368241
Node: downto368491
Node: else368706
Node: empty368916
Node: end369178
Node: eof369382
Node: eoln369672
Node: EpsReal369970
Node: eq370184
Node: erase370438
Node: Exit370691
Node: exp370898
Node: Export371195
Node: extend371409
Node: Extended371674
Node: extern371940
Node: external372161
Node: false372383
Node: far372596
Node: FileMode373350
Node: File373612
Node: FilePos373822
Node: FileSize374101
Node: FillChar374383
Node: flush374752
Node: for375010
Node: forward375461
Node: frac375676
Node: FreeMem375930
Node: Function376829
Node: ge377049
Node: Get377302
Node: GetFile377552
Node: GetMem378276
Node: GetTimeStamp379856
Node: goto380142
Node: gt380355
Node: Halt380605
Node: high380885
Node: if381215
Node: Im381414
Node: import381657
Node: Implementation383104
Node: in383341
Node: inc383551
Node: Index383870
Node: inherited384084
Node: inline384309
Node: InOutRes384531
Node: InOutResStr384799
Node: Input385075
Node: Insert385328
Node: int385623
Node: Integer385872
Node: Interface386819
Node: IOresult387048
Node: Label387309
Node: LastPosition387531
Node: le387823
Node: length388083
Node: ln388340
Node: LoCase388634
Node: LongCard388893
Node: LongInt389476
Node: LongestCard390320
Node: LongestInt390878
Node: LongestReal391451
Node: LongestWord391692
Node: LongReal392294
Node: LongWord392524
Node: low393137
Node: lt393481
Node: Mark393730
Node: max393977
Node: MaxChar394250
Node: MaxInt394467
Node: MaxReal394686
Node: MedCard394907
Node: MedInt395566
Node: MedReal396215
Node: MedWord396436
Node: min397120
Node: MinReal397396
Node: MkDir397612
Node: mod397871
Node: Module398131
Node: move398343
Node: MoveLeft398623
Node: MoveRight398918
Node: near399216
Node: ne399968
Node: New400217
Node: NewCString401060
Node: Nil401341
Node: not401550
Node: NULL401888
Node: object402190
Node: odd402977
Node: of403227
Node: only403427
Node: Operator403636
Node: or403853
Node: or else406463
Node: or_else407004
Node: ord409117
Node: others409370
Node: otherwise409587
Node: Output409813
Node: pack410066
Node: packed410426
Node: page412187
Node: pAnsiChar412470
Node: ParamCount412743
Node: ParamStr413586
Node: pChar413871
Node: Pointer414169
Node: polar414387
Node: pos414651
Node: Position414925
Node: pow415191
Node: pred415550
Node: Procedure417702
Node: Program417927
Node: protected418153
Node: PtrCard418381
Node: PtrInt418604
Node: PtrWord418823
Node: Put419040
Node: Re419290
Node: read419532
Node: readln419894
Node: ReadStr420208
Node: Real420484
Node: record420696
Node: Release422816
Node: rename423078
Node: repeat423359
Node: reset423575
Node: restricted423906
Node: Result424134
Node: return424355
Node: rewrite424573
Node: RmDir424909
Node: round425170
Node: RunError425430
Node: Seek425701
Node: SeekRead425984
Node: SeekUpdate426281
Node: SeekWrite426589
Node: Self426890
Node: set427101
Node: SetLength427310
Node: SetType428639
Node: ShortCard430244
Node: ShortInt430859
Node: ShortReal431671
Node: ShortWord431902
Node: Single432691
Node: shl432950
Node: shr433919
Node: sin435122
Node: SizeOf435418
Node: SmallInt436081
Node: sqr436795
Node: sqrt437729
Node: StandardError438817
Node: StandardInput439060
Node: StandardOutput439313
Node: static439561
Node: StdErr439786
Node: Str440035
Node: StrPCopy440565
Node: String440861
Node: String2CString441088
Node: SubStr441391
Node: succ442655
Node: Text444794
Node: then445001
Node: Time445208
Node: TimeStamp445512
Node: to446010
Node: to begin446220
Node: to end446439
Node: Trim446656
Node: true446910
Node: trunc447118
Node: Truncate447377
Node: Type447645
Node: TypeOf447858
Node: UnBind448895
Node: Unit449156
Node: unpack449367
Node: until449736
Node: UpCase449950
Node: update450210
Node: uses450540
Node: Val451798
Node: value452199
Node: Var452407
Node: virtual452615
Node: Void452830
Node: while453041
Node: with453251
Node: Word453459
Node: write454517
Node: writeln454934
Node: WriteStr455301
Node: xor455605
Node: GPC source457158
Node: Lexical analyzer459294
Node: Language definition461573
Node: Tree nodes465504
Node: Parameter passing470453
Node: GPI files472654
Node: AutoMake476953
Node: Keywords479489
Node: Built-in484208
Node: Extensions487563
Node: Extended Pascal537929
Node: Borland Pascal550526
Node: Borland compatibility551408
Node: IDE versus command line552162
Node: Comments and compiler directives555957
Node: Units; GPI files and AutoMake559500
Node: Optimization562367
Node: Debugging563394
Node: GPC inline assembler564527
Node: Objects565927
Node: Strings566421
Node: Typed constants567863
Node: Bit; byte and memory manipulation569038
Node: User-defined operators in GPC570407
Node: Data types in BP and GPC571500
Node: Files574567
Node: Built-in constants574904
Node: Built-in operators in BP and GPC575211
Node: Built-in Procedures and Functions575958
Node: Parameters576906
Node: Miscellaneous577984
Node: GPC bugs579805
Node: Support585836
Node: How to Contribute587437
Node: GPC notes592065
Node: PVS594696
Node: Set types597338
Node: GPC index600382

End Tag Table
