This is gpc.info, produced by makeinfo version 4.0 from gpc.texi.

INFO-DIR-SECTION GNU programming tools
START-INFO-DIR-ENTRY
* GPC: (gpc).                   The GNU Pascal Compiler.
END-INFO-DIR-ENTRY
INFO-DIR-SECTION Individual utilities
START-INFO-DIR-ENTRY
* GPC: (gpc)Invoking GPC.       The GNU Pascal Compiler.
END-INFO-DIR-ENTRY

   This file documents the GNU Pascal Compiler.

   Copyright (C) 1988, 1996-2000 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", "The GNU
Project", "The GNU Manifesto" and "Funding for Free Software" 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", "The GNU Project", "The GNU Manifesto" and "Funding for Free
Software" 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: Strings,  Next: StringUtils,  Prev: RegEx,  Up: GPC Units

BP compatibility: Strings
-------------------------

   The following listing contains the interface of the Strings unit.

   This is a compatibility unit to BP's `Strings' unit to handle C
style `#0'-terminated strings.

   The same functionality and much more is available in the Run Time
System, *Note Run Time System::, under clearer names (starting with a
`CString' prefix),

   Moreover, the use of `#0'-terminated C-style strings (`PChar' or
`CString') is generally not recommended in GPC, since GPC provides ways
to deal with Pascal-style strings of arbitrary and dynamic size in a
comfortable way, as well as automatic conversion to C-style strings in
order to call external C functions.

   Therefore, using this unit is not recommended in newly written
programs.

     {
     BP compatible Strings unit
     
     Copyright (C) 1999-2000 Free Software Foundation, Inc.
     
     Author: Frank Heckenbach <frank@pascal.gnu.de>
     
     This file is part of GNU Pascal.
     
     GNU Pascal 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, or (at your option)
     any later version.
     
     GNU Pascal 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 GNU Pascal; see the file COPYING. If not, write to the
     Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
     02111-1307, USA.
     
     As a special exception, if you link this file with files compiled
     with a GNU compiler to produce an executable, this does not cause
     the resulting executable to be covered by the GNU General Public
     License. This exception does not however invalidate any other
     reasons why the executable file might be covered by the GNU General
     Public License.
     }
     
     {$gnu-pascal}
     
     unit Strings;
     
     interface
     
     uses GPC;
     
     function  StrLen     (Src : CString) : SizeType;
       asmname '_p_strlen';
     function  StrEnd     (Src : CString) : CString; asmname '_p_strend';
     function  StrMove    (Dest, Source : CString; Count : SizeType) :
       CString; asmname '_p_strmove';
     function  StrCopy    (Dest, Source : CString) : CString;
       asmname '_p_strcpy';
     function  StrECopy   (Dest, Source : CString) : CString;
       asmname '_p_strecpy';
     function  StrLCopy   (Dest, Source : CString; MaxLen : SizeType) :
       CString; asmname '_p_strlcpy';
     function  StrPCopy   (Dest : CString; const Source : String) :
       CString; asmname '_p_cstringcopystring';
     function  StrCat     (Dest, Source : CString) : CString;
       asmname '_p_strcat';
     function  StrLCat    (Dest, Source : CString; MaxLen : SizeType) :
       CString; asmname '_p_strlcat';
     function  StrComp    (s1, s2 : CString) : Integer;
       asmname '_p_strcmp';
     function  StrIComp   (s1, s2 : CString) : Integer;
       asmname '_p_strcasecmp';
     function  StrLComp   (s1, s2 : CString; MaxLen : SizeType) :
       Integer; asmname '_p_strlcmp';
     function  StrLIComp  (s1, s2 : CString; MaxLen : SizeType) :
       Integer; asmname '_p_strlcasecmp';
     function  StrScan    (Src : CString; Ch : Char) : CString;
       asmname '_p_strscan';
     function  StrRScan   (Src : CString; Ch : Char) : CString;
       asmname '_p_strrscan';
     function  StrPos     (aString, SubString : CString) : CString;
       asmname '_p_strpos';
     function  StrRPos    (aString, SubString : CString) : CString;
       asmname '_p_strrpos';
     function  StrUpper   (s : CString) : CString; asmname '_p_strupper';
     function  StrLower   (s : CString) : CString; asmname '_p_strlower';
     function  StrPas     (aString : CString) : TString;
       asmname '_p_strpas';
     function  StrEmpty   (s : CString) : Boolean; asmname '_p_strempty';
     function  StrNew     (Src : CString) : CString; asmname '_p_strdup';
     procedure StrDispose (s : CString); asmname '_p_dispose';


File: gpc.info,  Node: StringUtils,  Next: System,  Prev: Strings,  Up: GPC Units

Higher level string handling
----------------------------

   The following listing contains the interface of the StringUtils unit.

   This unit provides some routines for string handling on a higher
level than those provided by the RTS.

     {
     Some routines for string handling on a higher level than those
     provided by the RTS.
     
     Copyright (C) 1999-2000 Free Software Foundation, Inc.
     
     Author: Frank Heckenbach <frank@pascal.gnu.de>
     
     This file is part of GNU Pascal.
     
     GNU Pascal 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, or (at your option)
     any later version.
     
     GNU Pascal 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 GNU Pascal; see the file COPYING. If not, write to the
     Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
     02111-1307, USA.
     
     As a special exception, if you link this file with files compiled
     with a GNU compiler to produce an executable, this does not cause
     the resulting executable to be covered by the GNU General Public
     License. This exception does not however invalidate any other
     reasons why the executable file might be covered by the GNU General
     Public License.
     }
     
     {$gnu-pascal}
     {$if __GPC_RELEASE__ < 20000814}
     {$error This unit requires GPC release 20000814 or newer.}
     {$endif}
     
     unit StringUtils;
     
     interface
     
     uses GPC;
     
     { Returns the number of disjoint occurences of SubStr in s. Returns
       0 if SubStr is empty. }
     function  StrCount (const SubStr : String; s : String) : Integer;
     
     { Returns s, with all disjoint occurences of Source replaced by
       Dest. }
     function  StrReplace (const s, Source, Dest : String) : TString;
     
     { Converts a digit character to its numeric value. Handles every
       base up to 36 (0 .. 9, a .. z, upper and lower case recognized).
       Returns -1 if the character is not a digit at all. If you want to
       use it for a base < 36, you have to check if the result is smaller
       than the base and not equal to -1. }
     function  Char2Digit (ch : Char) : Integer;
     
     { Encode a string in a printable format (quoted printable and
       surrounded with `"'). All occurences of `"' within the string are
       encoded, so the result string contains exactly two `"' characters
       (at the beginning and ending). This is useful to store arbitrary
       strings in text files while keeping them as readable as possible
       (which is the goal of the quoted printable encoding in general,
       RFC 1521, section 5.1) and being able to read them back losslessly
       (with UnQuoteString). }
     function  QuoteString (const s : String) : TString;
     
     { Decode a string encoded by QuoteString (removing the `"' and
       expanding quoted printable encoded characters). Returns True if
       successful and False if the string has an invalid form. A string
       returned by QuoteString is always valid. }
     function  UnQuoteString (var s : String) : Boolean;
     
     { Decode a quoted-printable string (not enclosed in `"', unlike for
       UnQuoteString). Returns True if successful and False if the string
       has an invalid form. }
     function  UnQPString (var s : String) : Boolean;
     
     { Replaces all tab characters in s with the appropriate amount of
       spaces, assuming tab stops at every TabSize columns. Returns True
       if successful and False if the expanded string would exceed the
       capacity of s. In the latter case, some, but not all of the tabs
       in s may have been expanded. }
     function  ExpandTabs (var s : String; TabSize : Integer) : Boolean;
     
     { Returns s, with all occurences of C style escape sequences (e.g.
       `\n') replaced by the characters they mean. If AllowOctal is True,
       also octal character specifications (e.g. `\007') are replaced. If
       RemoveQuoteChars is True, any other backslashes are removed (e.g.
       `\*' -> `*' and `\\' -> `\'), otherwise they are kept, and also
       `\\' is left as two backslashes then. }
     function  ExpandCEscapeSequences (const s : String;
       RemoveQuoteChars, AllowOctal : Boolean) : TString;
     
     { String hash table }
     
     const
       DefaultHashSize = 1403;
     
     type
       THash = Cardinal;
     
       PStrHashList = ^TStrHashList;
       TStrHashList = record
         Next : PStrHashList;
         s : PString;
         i : Integer;
         p : Pointer
       end;
     
       PStrHashTable = ^TStrHashTable;
       TStrHashTable (Size : Cardinal) = record
         CaseSensitive : Boolean;
         Table : array [0 .. Size - 1] of PStrHashList
       end;
     
     function  HashString          (const s : String) : THash;
     function  NewStrHashTable     (Size : Cardinal; CaseSensitive :
       Boolean) : PStrHashTable;
     procedure AddStrHashTable     (HashTable : PStrHashTable; s :
       String; i : Integer; p : Pointer);
     procedure DeleteStrHashTable  (HashTable : PStrHashTable; s :
       String);
     function  SearchStrHashTable  (HashTable : PStrHashTable; const s :
       String; var p : Pointer) : Integer; { p may be null }
     procedure DisposeStrHashTable (HashTable : PStrHashTable);


File: gpc.info,  Node: System,  Next: Trap,  Prev: StringUtils,  Up: GPC Units

BP compatibility: System
------------------------

   The following listing contains the interface of the System unit.

   This unit contains only BP's more exotic routines which are not
recommended to be used in new programs. Most of their functionality can
be achieved by more standard means already.

   _Note:_ `MemAvail' and `MaxAvail', provided in this unit, cannot
easily be achieved by other means. However, it is not recommended to
use them on any multi-tasking system at all, where memory is a shared
resource. The notes in the unit give some hints about how to avoid
using them.

   On special request, i.e., by defining the conditionals
`__BP_TYPE_SIZES__' and/or `__BP_RANDOM__', the unit also provides BP
compatible integer type sizes and a 100% BP compatible pseudo random
number generator.

     {
     BP compatible System unit for GPC
     
     This unit is released as part of the GNU Pascal project. It
     implements some rather exotic BP compatibility features. Even many
     BP programs don't need them, but they're here for maximum
     compatibility. Most of BP's System unit's features are built into
     the compiler or the RTS.
     
     The unit depends on the conditional defines `__BP_TYPE_SIZES__' and
     `__BP_RANDOM__'. If `__BP_TYPE_SIZES__' is defined (with the
     `-D__BP_TYPE_SIZES__' option), the integer data types will be
     redefined to the sizes they have in BP or Delphi. Note that this
     might cause problems, e.g. when passing var parameters of integer
     types between units that do and don't use System. However, of the BP
     compatibility units, only Dos and WinDos use such parameters, and
     they have been taken care of so they work.
     
     If `__BP_RANDOM__' is defined (`-D__BP_RANDOM__'), this unit will
     provide an exactly BP compatible pseudo random number generator. In
     particular, the range for integer randoms will be truncated to 16
     bits like in BP. The RandSeed variable is provided, and if it's set
     to the same value as BP's RandSeed, it produces exactly the same
     sequence of pseudo random numbers that BP's pseudo random number
     generator does (whoever might need this... ;-). Even the Randomize
     function will behave exactly like in BP. However, this will not be
     noted unless one explicitly tests for it.
     
     Copyright (C) 1998-2000 Free Software Foundation, Inc.
     
     Authors: Peter Gerwinski <peter@gerwinski.de>
              Prof. Abimbola A. Olowofoyeku <African_Chief@bigfoot.com>
              Frank Heckenbach <frank@pascal.gnu.de>
              Dominik Freche <dominik.freche@gmx.net>
     
     This file is part of GNU Pascal.
     
     GNU Pascal 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, or (at your option)
     any later version.
     
     GNU Pascal 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 GNU Pascal; see the file COPYING. If not, write to the
     Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
     02111-1307, USA.
     
     As a special exception, if you link this file with files compiled
     with a GNU compiler to produce an executable, this does not cause
     the resulting executable to be covered by the GNU General Public
     License. This exception does not however invalidate any other
     reasons why the executable file might be covered by the GNU General
     Public License.
     }
     
     {$gnu-pascal}
     {$if __GPC_RELEASE__ < 20000412}
     {$error This unit requires GPC release 20000412 or newer.}
     {$endif}
     
     unit System;
     
     interface
     
     uses GPC;
     
     var
       { Chain of procedures to be executed at the end of the program }
       ExitProc : ^procedure = nil;
     
       { Contains all the command line arguments passed to the program,
         concatenated, with spaces between them }
       CmdLine : CString;
     
       {$ifdef __BP_RANDOM__}
       { Random seed, initialized by Randomize, but can also be set
         explicitly }
       RandSeed : Integer (32) = 0;
       {$endif}
     
     type
       OrigInt = Integer;
       OrigWord = Word;
     
       { needed in the Dos unit }
       Int7 = Integer (7);
       Word16 = Word (16);
       Word32 = Word (32);
     
       { Delphi }
       SmallInt = Integer  (16);
       DWord    = Cardinal (32);
     
       { Short BP compatible type sizes if wanted }
       {$ifdef __BP_TYPE_SIZES__}
       ByteBool = Boolean  (8);
       WordBool = Boolean  (16);
       LongBool = Boolean  (32);
       Boolean  = ByteBool;      { important in packed records and arrays
       }
       ShortInt = Integer  (8);
       Byte     = Cardinal (8);
       Word     = Cardinal (16);
       LongInt  = Integer  (32);
       Comp     = Integer  (64);
       LongWord = Cardinal (32); { Delphi }
       Integer  = Integer  (16);
       {$endif}
     
       (*@@ doesn't work well (dialec3.pas) -- when GPC gets short
            strings, it will be unnecessary
       {$ifdef __BORLAND_PASCAL__}
       String = String [255];
       {$endif} *)
     
     const
       MaxInt     = High (Integer);
       MaxLongInt = High (LongInt);
     
     { Return the lowest-order byte of x }
     function  Lo (x : LongestInt) : Byte;
     
     { Return the lowest-but-one-order byte of x }
     function  Hi (x : LongestInt) : Byte;
     
     { Swap the lowest- and lowest-but-one-order bytes, mask out the
       higher ones }
     function  Swap (x : LongestInt) : Word;
     
     { Store the current directory name (on the given drive number if
       drive <> 0) in s }
     procedure GetDir (Drive : Byte; var s : String);
     
     { Dummy routine for compatibility. @@Use two overloaded versions
       rather than varargs when possible. }
     procedure SetTextBuf (var f : Text; var Buf; ...);
     
     { Mostly useless BP compatible variables }
     var
       SelectorInc : Word = $1000;
       Seg0040 : Word = $40;
       SegA000 : Word = $a000;
       SegB000 : Word = $b000;
       SegB800 : Word = $b800;
       Test8086 : Byte = 2;
       Test8087 : Byte = 3; { floating-point arithmetic is emulated
                              transparently by the OS if not present
                              in hardware }
       OvrCodeList : Word = 0;
       OvrHeapSize : Word = 0;
       OvrDebugPtr : Pointer = nil;
       OvrHeapOrg : Word = 0;
       OvrHeapPtr : Word = 0;
       OvrHeapEnd : Word = 0;
       OvrLoadList : Word = 0;
       OvrDosHandle : Word = 0;
       OvrEmsHandle : Word = $ffff;
       HeapOrg : Pointer absolute HeapBegin;
       HeapPtr : Pointer absolute HeapHigh;
       HeapEnd : Pointer = Pointer (High (PtrCard));
       FreeList : Pointer = nil;
       FreeZero : Pointer = nil;
       StackLimit : Word = 0;
       HeapList : Word = 0;
       HeapLimit : Word = 1024;
       HeapBlock : Word = 8192;
       HeapAllocFlags : Word = 2;
       CmdShow : Integer = 0;
       SaveInt00 : Pointer = nil;
       SaveInt02 : Pointer = nil;
       SaveInt0C : Pointer = nil;
       SaveInt0D : Pointer = nil;
       SaveInt1B : Pointer = nil;
       SaveInt21 : Pointer = nil;
       SaveInt23 : Pointer = nil;
       SaveInt24 : Pointer = nil;
       SaveInt34 : Pointer = nil;
       SaveInt35 : Pointer = nil;
       SaveInt36 : Pointer = nil;
       SaveInt37 : Pointer = nil;
       SaveInt38 : Pointer = nil;
       SaveInt39 : Pointer = nil;
       SaveInt3A : Pointer = nil;
       SaveInt3B : Pointer = nil;
       SaveInt3C : Pointer = nil;
       SaveInt3D : Pointer = nil;
       SaveInt3E : Pointer = nil;
       SaveInt3F : Pointer = nil;
       SaveInt75 : Pointer = nil;
       RealModeRegs : array [0 .. 49] of Byte =
         (0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
          0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
          0, 0, 0, 0, 0, 0, 0, 0);
     
     { Mostly useless BP compatible pointer functions }
     function  Ofs (const X) : PtrWord;
     function  Seg (const X) : PtrWord;
     function  Ptr (Seg, Ofs : PtrWord) : Pointer;
     function  CSeg : PtrWord;
     function  DSeg : PtrWord;
     function  SSeg : PtrWord;
     function  SPtr : PtrWord;
     
     {
       Routines to handle BP's 6 byte `Real' type which is formatted like
       this:
     
       47                                                   0
       -|------- -------- -------- -------- --------|--------
        |                                           |
        +----------+                   +------------+
       47 Sign Bit |  8..46 Mantissa   | 0..7 Biased Exponent
     
       This format does not support infinities, NaNs and denormalized
       numbers. The first digit after the binary point is not stored and
       assumed to be 1. (This is called the normalized representation of
       a binary floating point number.)
     
       In GPC, this type is represented by the type `BPReal' which is
       binary compatible to BP's type, and can therefore be used in
       connection with binary files used by BP programs.
     
       The functions `RealToBPReal' and `BPRealToReal' convert between
       this type and GPC's `Real' type. Apart from that, `BPReal' should
       be treated as opaque.
     
       The variables `BPRealIgnoreOverflow' and `BPRealIgnoreUnderflow'
       determine what to do in the case of overflows and underflows. The
       default values are BP compatible.
     }
     
     var
       { Ignore overflows, and use the highest possible value instead. }
       BPRealIgnoreOverflow  : Boolean = False;
     
       { Ignore underflows, and use 0 instead. This is BP's behaviour,
         but has the disadvantage of diminishing computation precision. }
       BPRealIgnoreUnderflow : Boolean = True;
     
     type
       BPReal = record
         Format : array [1 .. 6] of Cardinal (8)
       end;
     
     function RealToBPReal (R : Real) : BPReal;
     function BPRealToReal (const BR : BPReal) : Real;
     
     { Heap management stuff }
     
     const
       { Possible return values for HeapError }
       HeapErrorRunError = 0;
       HeapErrorNil      = 1;
       HeapErrorRetry    = 2;
     
     var
       { If assigned to a function, it will be called when memory
         allocations do not find enough free memory. Its return value
         determines if a run time error should be raised (the default),
         or nil should be returned, or the allocation should be retried
         (causing the routine to be called again if the allocation still
         doesn't succeed).
     
         Notes:
     
         - Returning nil can cause some routines of the RTS and units
           (shipped with GPC or third-party) to crash when they don't
           expect nil, so better don't use this mechanism, but rather
           CGetMem where needed.
     
         - Letting the allocation be retried, of course, only makes sense
           if the routine freed some memory before -- otherwise it will
           cause an infinite loop! So, a meaningful HeapError routine
           should dispose of some temporary objects, if available, and
           return HeapErrorRetry, and return HeapErrorRunError when no
           (more) of them are available.
       }
       HeapError : ^function (Size : Word) : Integer = nil;
     
     { Just returns HeapErrorNil. When this function is assigned to
       HeapError, GetMem and New will return a nil pointer instead of
       causing a runtime error when the allocation fails. See the comment
       for HeapError above. }
     function  HeapErrorNilReturn (Size : Word) : Integer;
     
     { Return the total free memory/biggest free memory block. Except
       under Win32 and DJGPP, these are expensive routines -- try to
       avoid them. Under Win32, MaxAvail returns the same as MemAvail, so
       don't rely on being able to allocate a block of memory as big as
       MaxAvail indicates. Generally it's preferable to not use these
       functions at all in order to do a safe allocation, but just try to
       allocate the memory needed using CGetMem, and check for a nil
       result. }
     function  MemAvail : OrigInt;
     function  MaxAvail : OrigInt;


File: gpc.info,  Node: Trap,  Next: Turbo3,  Prev: System,  Up: GPC Units

Trap runtime errors
-------------------

   The following listing contains the interface of the Trap unit.

   This unit allows you to trap runtime errors, so a runtime error will
not abort the program, but pass the control back to a point within the
program. Use with care, and read the notes in the interface, please.

     {
     Trapping runtime errors
     
     The Trap unit allows you to trap runtime errors, so a runtime error
     will not abort the program, but pass the control back to a point
     within the program.
     
     The usage is simple. The TrapExec procedure can be called with a
     function (p) as an argument. p must take a boolean argument. p will
     immediately be called with False given as its argument. When a
     runtime error would otherwise be caused while p is active, p will
     instead be called again with True as its argument. After p returns,
     runtime errors will not be trapped.
     
     When the program terminates (e.g. by reaching its end or by a Halt
     statement) and a runtime error was trapped during the run, Trap will
     set the ExitCode and ErrorAddr variables to indicate the trapped
     error.
     
     Notes:
     
     - After trapping a runtime error, your program might not be in a
       stable state. If the runtime error was a "minor" one (such as a
       range checking or arithmetic error), it should not be a problem.
       But if you e.g. write a larger application and use Trap to prevent
       a sudden abort caused by an unexpected runtime error, you should
       make the program terminate regularly as soon as possible after a
       trapped error (maybe telling the user to save the data, then
       terminate the program and report the error to you).
     
     - Since the trapping mechanism *jumps* back, it has all the negative
       effects that a (non-local!) `goto' can have! You should be aware
       of the consequences of all active procedures being terminated at
       an arbitrary point!
     
     Copyright (C) 1996-2000 Free Software Foundation, Inc.
     
     Author: Frank Heckenbach <frank@pascal.gnu.de>
     
     This file is part of GNU Pascal.
     
     GNU Pascal 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, or (at your option)
     any later version.
     
     GNU Pascal 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 GNU Pascal; see the file COPYING. If not, write to the
     Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
     02111-1307, USA.
     
     As a special exception, if you link this file with files compiled
     with a GNU compiler to produce an executable, this does not cause
     the resulting executable to be covered by the GNU General Public
     License. This exception does not however invalidate any other
     reasons why the executable file might be covered by the GNU General
     Public License.
     }
     
     {$gnu-pascal}
     
     unit Trap;
     
     interface
     
     uses GPC;
     
     var
       TrappedExitCode : Integer = 0;
       TrappedErrorAddr : Pointer = nil;
       TrappedErrorMessageString : TString = '';
     
     procedure TrapExec (procedure p (Trapped : Boolean));


File: gpc.info,  Node: Turbo3,  Next: WinDos,  Prev: Trap,  Up: GPC Units

BP compatibility: Turbo3
------------------------

   The following listing contains the interface of the Turbo3 unit.

   This is a compatibility unit to BP's `Turbo3' compatibility unit to
TP3. ;-) It is not meant to be used in any newly written code.

     {
     Turbo Pascal 3.0 compatibility unit
     
     Copyright (C) 1998-2000 Free Software Foundation, Inc.
     
     Author: Frank Heckenbach <frank@pascal.gnu.de>
     
     This file is part of GNU Pascal.
     
     GNU Pascal 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, or (at your option)
     any later version.
     
     GNU Pascal 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 GNU Pascal; see the file COPYING. If not, write to the
     Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
     02111-1307, USA.
     
     As a special exception, if you link this file with files compiled
     with a GNU compiler to produce an executable, this does not cause
     the resulting executable to be covered by the GNU General Public
     License. This exception does not however invalidate any other
     reasons why the executable file might be covered by the GNU General
     Public License.
     }
     
     {$gnu-pascal}
     {$if __GPC_RELEASE__ < 20000412}
     {$error This unit requires GPC release 20000412 or newer.}
     {$endif}
     
     unit Turbo3;
     
     interface
     
     uses GPC, System, CRT;
     
     var
       Kbd : Text;
       CBreak : Boolean absolute CheckBreak;
     
     procedure AssignKbd (var F : (*AnyFile*)Text);
     function  (*@@fjf260*)MemAvail3 : Integer;
     function  (*@@fjf260*)MaxAvail3 : Integer;
     function  LongFileSize (var F : AnyFile) : Real;
     function  LongFilePos  (var F : AnyFile) : Real;
     procedure LongSeek     (var F : AnyFile; aPosition : Real);
     procedure (*@@fjf260*)LowVideo3;
     procedure (*@@fjf260*)HighVideo3;


File: gpc.info,  Node: WinDos,  Prev: Turbo3,  Up: GPC Units

BP compatibility: WinDos
------------------------

   The following listing contains the interface of the WinDos unit.

   This is a portable implementation of most routines from BP's
`WinDos' unit. A few routines that are Dos - or even x86 real mode -
specific, are only available if `__BP_UNPORTABLE_ROUTINES__' is defined,
*Note BP Incompatibilities::.

   The same functionality and much more is available in the Run Time
System, *Note Run Time System::. The RTS routines usually have
different names and/or easier and less limiting interfaces (e.g.
`ReadDir' etc. vs. `FindFirst' etc.), and are often more efficient.

   Therefore, using this unit is not recommended in newly written
programs.

     {
     Mostly BP compatible portable WinDos unit
     
     This unit supports most, but not all, of the routines and
     declarations of BP's WinDos unit.
     
     NOTES:
     
     - The procedures GetIntVec and SetIntVec are not supported since
       they make only sense for Dos real-mode programs (and GPC compiled
       programs do not run in real-mode, even on x86 under Dos). The
       procedures Intr and MsDos are only supported under DJGPP if
       `__BP_UNPORTABLE_ROUTINES__' is defined (with the
       `-D__BP_UNPORTABLE_ROUTINES__' option). A few other routines are
       also only supported with this define, but on all platforms (but
       they are crude hacks, that's why they are not supported without
       this define).
     
     - The internal structure of file variables (TFileRec and TTextRec)
       is different in GPC. However, as far as TFDDs are concerned, there
       are other ways to achieve the same in GPC, see the GPC unit.
     
     Copyright (C) 1998-2000 Free Software Foundation, Inc.
     
     Author: Frank Heckenbach <frank@pascal.gnu.de>
     
     This file is part of GNU Pascal.
     
     GNU Pascal 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, or (at your option)
     any later version.
     
     GNU Pascal 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 GNU Pascal; see the file COPYING. If not, write to the
     Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
     02111-1307, USA.
     
     As a special exception, if you link this file with files compiled
     with a GNU compiler to produce an executable, this does not cause
     the resulting executable to be covered by the GNU General Public
     License. This exception does not however invalidate any other
     reasons why the executable file might be covered by the GNU General
     Public License.
     }
     
     {$gnu-pascal}
     
     unit WinDos;
     
     interface
     
     uses GPC, System, Dos;
     
     const
       { File attribute constants }
       faReadOnly  = ReadOnly;
       faHidden    = Hidden;    { set for dot files except `.' and `..' }
       faSysFile   = SysFile;   { not supported }
       faVolumeID  = VolumeID;  { not supported }
       faDirectory = Directory;
       faArchive   = Archive;   { means: not executable }
       faAnyFile   = AnyFile;
     
       { Maximum file name component string lengths }
       fsPathName  = 79;
       fsDirectory = 67;
       fsFileName  = 8;
       fsExtension = 4;
     
       { FileSplit return flags }
       fcExtension = 1;
       fcFileName  = 2;
       fcDirectory = 4;
       fcWildcards = 8;
     
       { Flag bit masks -- only used by the unportable Dos routines }
       FCarry     = 1;
       FParity    = 4;
       FAuxiliary = $10;
       FZero      = $40;
       FSign      = $80;
       FOverflow  = $800;
     
     type
       PTextBuf = ^TTextBuf;
       TTextBuf = TextBuf;
     
       { Search record used by FindFirst and FindNext }
       TSearchRec = {$ifdef __BP_TYPE_SIZES__} packed {$endif} record
          Fill : SearchRecFill;
          Attr : Byte8;
          Time, Size : LongInt;
          Name : {$ifdef __BP_TYPE_SIZES__}
                 packed array [0 .. 12] of Char
                 {$else}
                 TStringBuf
                 {$endif};
          Reserved : SearchRec
       end;
     
       { Date and time record used by PackTime and UnpackTime }
       TDateTime = DateTime;
     
       { 8086 CPU registers -- only used by the unportable Dos routines }
       TRegisters = Registers;
     
     var
       { Error status variable }
       DosError : Integer; external;
     
     procedure GetDate (var Year, Month, Day, DayOfWeek : Word);
       asmname '_p_getdate';
     procedure GetTime (var Hour, Minute, Second, Sec100 : Word);
       asmname '_p_gettime';
     procedure (*@@fjf260*)WGetCBreak (var BreakOn : Boolean);
       asmname '_p_getcbreak';
     procedure (*@@fjf260*)WSetCBreak (BreakOn : Boolean);
       asmname '_p_setcbreak';
     procedure (*@@fjf260*)WGetVerify (var VerifyOn : Boolean);
       asmname '_p_getverify';
     procedure (*@@fjf260*)WSetVerify (VerifyOn : Boolean);
       asmname '_p_setverify';
     function  DiskFree (Drive : Byte) : LongInt; asmname '_p_diskfree';
     function  DiskSize (Drive : Byte) : LongInt; asmname '_p_disksize';
     procedure GetFAttr (var F : GPC_AnyFile; var Attr : Word);
       asmname '_p_getfattr';
     procedure SetFAttr (var F : GPC_AnyFile; Attr : Word);
       asmname '_p_setfattr';
     procedure GetFTime (var F : GPC_AnyFile; var aTime : LongInt);
       asmname '_p_getftime';
     procedure SetFTime (var F : GPC_AnyFile; aTime : LongInt);
       asmname '_p_setftime';
     
     { FindFirst and FindNext are quite inefficient since they emulate
       all the brain-dead Dos stuff. If at all possible, the standard
       routines OpenDir, ReadDir and CloseDir (in the GPC unit) should be
       used instead. }
     procedure (*@@fjf260*)WFindFirst (Path : PChar; Attr : Word; var
       SR : TSearchRec);
     procedure (*@@fjf260*)WFindNext  (var SR : TSearchRec);
     
     procedure (*@@fjf260*)WFindClose (var SR : TSearchRec);
     procedure UnpackTime (P : LongInt; var T : TDateTime);
       asmname '_p_unpacktime';
     procedure PackTime (const T : TDateTime; var P : LongInt);
       asmname '_p_packtime';
     function  FileSearch (Dest, Name, List : PChar) : PChar;
     function  FileExpand (Dest, Name : PChar) : PChar;
     function  FileSplit (Path, Dir, Name, Ext : PChar) : Word;
     function  GetCurDir (Dir : PChar; Drive : Byte) : PChar;
     procedure SetCurDir (Dir : PChar);
     procedure CreateDir (Dir : PChar);
     procedure RemoveDir (Dir : PChar);
     function  GetArgCount : Integer;
     function  GetArgStr (Dest : PChar; ArgIndex : Integer; MaxLen :
       Word) : PChar;
     function  GetEnvVar (VarName : PChar) : PChar;
       asmname '_p_cstringgetenv';
     
     {$ifdef __BP_UNPORTABLE_ROUTINES__}
     {$ifdef DJGPP}
     procedure (*@@fjf260*)WIntr (IntNo : Byte; var Regs : Registers);
       asmname '_p_intr';
     procedure (*@@fjf260*)WMsDos (var Regs : Registers);
       asmname '_p_msdos';
     {$endif}
     function  (*@@fjf260*)WDosVersion : Word; asmname '_p_dosversion';
     procedure (*@@fjf260*)WSetDate (Year, Month, Day : Word);
       asmname '_p_setdate';
     procedure (*@@fjf260*)WSetTime (Hour, Minute, Second, Sec100 :
       Word); asmname '_p_settime';
     {$endif}


File: gpc.info,  Node: Reference,  Next: Keywords,  Prev: Programming,  Up: Top

The Alphabetical GPC Language Reference
***************************************

   *This chapter is still under development. All identifiers are
listed, but not all with explanations.*

   This chapter contains an alphabetical list of all built-in
identifiers of the GNU Pascal compiler. For detailed and comprehensive
description of syntax and reserved words, see *Note Programming::. This
chapter explains only built-in procedures and functions in detail. It
does not cover extensions provided by external units and libraries
which are supposed to come with their own documentation.

* Menu:

* Abs::
* absolute::
* abstract::
* 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::
* Card::
* Cardinal::
* case::
* Char::
* ChDir::
* Chr::
* C_Language::
* class::
* Close::
* Cmplx::
* Comp::
* Complex::
* Concat::
* Conjugate::
* const::
* constructor::
* Continue::
* Copy::
* Cos::
* CString::
* CString2String::
* CStringCopyString::
* Date::
* Dec::
* DefineSize::
* Delete::
* destructor::
* Dispose::
* div::
* do::
* Double::
* downto::
* else::
* Empty::
* end::
* EOF::
* EOLn::
* EpsReal::
* Eq::
* Erase::
* Exclude::
* Exit::
* Exp::
* export::
* exports::
* Extend::
* Extended::
* extern::
* external::
* Fail::
* False::
* far::
* file::
* FileMode::
* FilePos::
* FileSize::
* FillChar::
* Flush::
* for::
* forward::
* Frac::
* FrameAddress::
* FreeMem::
* function::
* GE::
* Get::
* GetMem::
* GetTimeStamp::
* goto::
* GT::
* Halt::
* High::
* if::
* Im::
* implementation::
* import::
* in::
* Inc::
* Include::
* Index::
* inherited::
* inline::
* InOutRes::
* InOutResStr::
* Input::
* Insert::
* Int::
* Integer::
* interface::
* interrupt::
* IOResult::
* is::
* label::
* LastPosition::
* LE::
* Length::
* library::
* Ln::
* LoCase::
* LongBool::
* LongCard::
* LongestBool::
* LongestCard::
* LongestInt::
* LongestReal::
* LongestWord::
* LongInt::
* LongReal::
* LongWord::
* Low::
* LT::
* Mark::
* Max::
* MaxChar::
* MaxInt::
* MaxReal::
* MedBool::
* MedCard::
* MedInt::
* MedReal::
* MedWord::
* Min::
* MinReal::
* MkDir::
* mod::
* module::
* Move::
* MoveLeft::
* MoveRight::
* Name::
* NE::
* near::
* New::
* NewCString::
* nil::
* not::
* Null::
* object::
* Odd::
* of::
* only::
* operator::
* or::
* or else::
* Ord::
* or_else::
* otherwise::
* Output::
* Override::
* Pack::
* packed::
* Page::
* PAnsiChar::
* ParamCount::
* ParamStr::
* PChar::
* Pi::
* Pointer::
* Polar::
* Pos::
* Position::
* pow::
* Pred::
* private::
* procedure::
* program::
* property::
* protected::
* PtrCard::
* PtrDiffType::
* PtrInt::
* PtrWord::
* public::
* published::
* Put::
* qualified::
* Random::
* Randomize::
* Re::
* Read::
* ReadLn::
* ReadStr::
* Real::
* record::
* register::
* Release::
* Rename::
* repeat::
* Reset::
* resident::
* restricted::
* Result::
* Return::
* ReturnAddress::
* Rewrite::
* RmDir::
* Root::
* Round::
* RunError::
* Seek::
* SeekRead::
* SeekUpdate::
* SeekWrite::
* segment::
* Self::
* set::
* SetFileTime::
* SetLength::
* SetType::
* shl::
* ShortBool::
* ShortCard::
* ShortInt::
* ShortReal::
* ShortWord::
* shr::
* Sin::
* Single::
* SizeOf::
* SizeType::
* SmallInt::
* Sqr::
* SqRt::
* StandardError::
* StandardInput::
* StandardOutput::
* static::
* StdErr::
* Str::
* String::
* String2CString::
* SubStr::
* Succ::
* Text::
* TextWritable::
* then::
* Time::
* TimeStamp::
* to::
* to begin do::
* to end do::
* Trim::
* True::
* Trunc::
* Truncate::
* type::
* type of::
* TypeOf::
* UnBind::
* unit::
* Unpack::
* until::
* UpCase::
* Update::
* uses::
* Val::
* value::
* var::
* view::
* virtual::
* Void::
* volatile::
* while::
* with::
* Word::
* WordBool::
* Write::
* WriteLn::
* WriteStr::
* xor::


File: gpc.info,  Node: Abs,  Next: absolute,  Up: Reference

Abs
===

Synopsis
--------

     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
       if x < 0 then
         Abs := -x
       else
         Abs := x
     end;

whereas for complex values it is

     function Abs (x: Complex): Real;
     begin
       Abs := SqRt (x * Conjugate (x))
     end;

Conforming to
-------------

   The function `Abs' is defined in ISO-7185 Standard Pascal; its
application to complex values is defined in ISO-10206 Extended Pascal.

Example
-------

     program AbsDemo;
     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: abstract,  Prev: Abs,  Up: Reference

absolute
========

Synopsis
--------

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

   GPC also allows explicit type casts. Variant records (as defined in
ISO-7185 Standard Pascal), however, have no _guaranteed_ overlaying and
are therefore _not_ suitable for 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.

Conforming to
-------------

   `absolute' is a Borland Pascal extension.

   Borland Pascal 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 Pascal extension.

Example
-------

     program AbsoluteDemo;
     
     {$X+}
     
     const
       IOMem = $f0000000;
     
     var
       Mem: array [0 .. High (Cardinal)] of Byte absolute 0;
     
       { This address has no actual meaning }
       MyPort: Byte absolute IOMem + $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;
     
       { Look at the internal representation of a real variable. }
       for i := 1 to SizeOf (Real) do
         Write (a [i] : 4);
       WriteLn;
     
       { The same again, more ugly... }
       for i := 1 to SizeOf (Real) do
         Write (b : 4);
       WriteLn;
     
       { And yes, there's an even more ugly way to do it... }
       for i := 1 to SizeOf (Real) do
         Write (Mem [PtrCard (@x) + i - 1] : 4);
       WriteLn
     end.

See also
--------

   *Note record::, *Note Type Casts::.


File: gpc.info,  Node: abstract,  Next: Addr,  Prev: absolute,  Up: Reference

abstract
========

   Not yet implemented.

Synopsis
--------

Description
-----------

Conforming to
-------------

Example
-------

See also
--------


File: gpc.info,  Node: Addr,  Next: AlignOf,  Prev: abstract,  Up: Reference

Addr
====

Synopsis
--------

     function Addr (const Foo): Pointer;

Description
-----------

   `Addr' returns the address of its argument. It is equivalent to the
address operator and provided for compatibility with Borland Pascal
which in turn implements it for backward-compatibility with Turbo
Pascal.

Conforming to
-------------

   `Addr' is a Borland Pascal extension.

Example
-------

     program AddrDemo;
     var
       Foo: ^Integer;
       Bar: Integer;
     begin
       Foo := Addr (Bar);  { Let `Foo' point to `Bar'. }
       Bar := 17;
       Foo^ := 42;  { Change the value of `Bar' to 42 }
       WriteLn (Bar)
     end.

See also
--------

   *Note Operators::.


File: gpc.info,  Node: AlignOf,  Next: all,  Prev: Addr,  Up: Reference

AlignOf
=======

Synopsis
--------

     function AlignOf (var x): Integer;

Description
-----------

   Returns the alignment of a type or variable in bytes.

Conforming to
-------------

   `AlignOf' is a GNU extension.

Example
-------

     program AlignOfDemo;
     var
       a: Integer;
       b: array [1 .. 8] of Char;
     begin
       WriteLn (AlignOf (a));  { Alignment of `Integer'; usually 4 bytes. }
       WriteLn (AlignOf (b));  { Alignment of `Char'; usually 1 byte. }
     end.

   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
===

Synopsis
--------

     export foo = 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.

Conforming to
-------------

   `All' is a GNU extension.

Example
-------

     program AllDemo;
     
     import AllInterface in 'allmodule.pas';
     
     begin
       Bar (a);
       WriteLn (b)
     end.

     module AllModule interface;
     
     export
       AllInterface = all;  { Same as `AllInterface = (a, b, Bar);' }
     
     var
       a, b: Integer;
     
     procedure Bar (i: Integer);
     
     end.
     
     module AllModule implementation;
     
     procedure Bar (i: Integer);
     begin
       b := a
     end;
     
     to begin do
       a := 42;
     
     end.

See also
--------

   *Note Modules::.

