This is ../p/doc/info/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-2002 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: 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-2002 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,I-}
     {$if __GPC_RELEASE__ < 20000814}
     {$error This unit requires GPC release 20000814 or newer.}
     {$endif}
     
     unit StringUtils;
     
     interface
     
     uses GPC;
     
     { Various routines }
     
     { Appends Source to s, truncating the result if necessary. }
     procedure AppendStr (var s: String; const Source: String);
     
     { Cuts s to MaxLength characters. If s is already MaxLength
       characters or shorter, it doesn't change anything. }
     procedure StrCut (var s: String; MaxLength: Integer);
     
     { 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;
     
     { Sets of characters accepted for `True' and `False' by
       Char2Boolean and StrReadBoolean. }
     var
       CharactersTrue : CharSet = ['Y', 'y'];
       CharactersFalse: CharSet = ['N', 'n'];
     
     { If ch is an element of CharactersTrue, Dest is set to True,
       otherwise if it is an element of CharactersFalse, Dest is set to
       False. In both cases True is returned. If ch is not an element of
       either set, Dest is set to False and False is returned. }
     function  Char2Boolean (ch: Char; var Dest: Boolean): Boolean;
     
     { 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,
       see 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. In the latter case, it still decodes as much
       as is valid, even after the error position. }
     function  UnQPString (var s: String): Boolean;
     
     { Quotes a string as done in shells, i.e. all special characters are
       enclosed in either `"' or `'', where `"', `$' and ``' are always
       enclosed in `'' and `'' is always enclosed in `"'. }
     function  ShellQuoteString (const s: String): TString;
     
     { 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;
     
     { Routines for TPStrings }
     
     { Initialise a TPStrings variable, allocate Size characters for each
       element. This procedure does not dispose of any previously
       allocated storage, so if you use it on a previously used variable
       without freeing the storage yourself, this might cause memory
       leaks. }
     procedure AllocateTPStrings (var Strings: TPStrings; Size: Integer);
     
     { Clears all elements (set them to empty strings), does not free any
       storage. }
     procedure ClearTPStrings (var Strings: TPStrings);
     
     { Divide a string into substrings, using Separators as separator. A
       single trailing separator is ignored. Further trailing separators
       as well as any leading separators and multiple separators in a row
       produce empty substrings. }
     function TokenizeString (const Source: String; Separators: CharSet):
       PPStrings;
     
     { Divide a string into substrings, using SpaceCharacters as
       separators. The splitting is done according the usual rules of
       shells, using (and removing) single and double quotes and
       QuotingCharacter. Multiple, leading and trailing separators are
       ignored. If there is an error, a message will be stored in ErrMsg,
       and nil will be returned. Nil will also be returned (without an
       error message) if s in empty. }
     function ShellTokenizeString (const s: String; var ErrMsg: String):
       PPStrings;
     
     { String parsing routines }
     
     { All the following StrReadFoo functions behave similarly. They read
       items from a string s, starting at index i, to a variable Dest.
       They skip any space characters (spaces and tabs) by incrementing i
       first. They return True if successful, False otherwise. i is
       incremented accordingly if successful, otherwise i is left
       unchanged, apart from the skipping of space characters, and Dest
       is undefined. This behaviour makes it easy to use the functions in
       a row like this:
     
         i := 1;
         if StrReadInt    (s, i, Size)  and StrReadComma (s, i) and
            StrReadQuoted (s, i, Name)  and StrReadComma (s, i) and
            ...
            StrReadReal   (s, i, Angle) and (i > Length (s)) then ...
     
       (The check `i > Length (s)' is in case you don't want to accept
       trailing "garbage".) }
     
     { Just skip any space characters as described above. }
     procedure StrSkipSpaces (const s: String; var i: Integer);
     
     { Read a quoted string (as produced by QuoteString) from a string
       and unquote the result using UnQuoteString. It is considered
       failure if the result (unquoted) would be longer than the capacity
       of Dest. }
     function  StrReadQuoted (const s: String; var i: Integer; var Dest:
       String): Boolean;
     
     { Read a string delimited with Delimiter from a string and return
       the result with the delimiters removed. It is considered failure
       if the result (without delimiters) would be longer than the
       capacity of Dest. }
     function  StrReadDelimited (const s: String; var i: Integer; var
       Dest: String; Delimiter: Char): Boolean;
     
     { Read a word (consisting of anything but space characters and
       commas) from a string. It is considered failure if the result
       would be longer than the capacity of Dest. }
     function  StrReadWord (const s: String; var i: Integer; var Dest:
       String): Boolean;
     
     { Check that a certain string is contained in s (after possible
       space characters). }
     function  StrReadConst (const s: String; var i: Integer; const
       Expected: String): Boolean;
     
     { A simpler to use version of StrReadConst that expects a `,'. }
     function  StrReadComma (const s: String; var i: Integer): Boolean;
     
     { Read an integer number from a string. }
     function  StrReadInt (const s: String; var i: Integer; var Dest:
       Integer): Boolean;
     
     { Read a real number from a string. }
     function  StrReadReal (const s: String; var i: Integer; var Dest:
       Real): Boolean;
     
     { Read a Boolean value, represented by a single character
       from CharactersTrue or CharactersFalse (cf. Char2Boolean), from a
       string. }
     function  StrReadBoolean (const s: String; var i: Integer; var Dest:
       Boolean): Boolean;
     
     { Read an enumerated value, i.e., one of the entries of IDs, from a
       string, and stores the ordinal value, i.e., the index in IDs
       (always zero-based) in Dest. }
     function  StrReadEnum (const s: String; var i: Integer; var Dest:
       Integer; var IDs: array of PString): Boolean;
     
     { 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 StrHashTableUsage   (HashTable: PStrHashTable; var
       Entries, Slots: Integer);
     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__', `__BP_RANDOM__' and/or `__BP_PARAMSTR_0__', the
unit also provides BP compatible integer type sizes, a 100% BP
compatible pseudo random number generator and/or BP compatible
`ParamStr (0)' behaviour (the latter, however, only on some systems).

     { BP and partly Delphi compatible System unit for GPC
     
       This unit is released as part of the GNU Pascal project. It
       implements some rather exotic BP and Delphi compatibility
       features. Even many BP and Delphi programs don't need them, but
       they're here for maximum compatibility. Most of BP's and Delphi's
       System units' features are built into the compiler or the RTS.
     
       Note: The things in this unit are really exotic. If you haven't
       used BP or Delphi before, you don't want to look at this unit. :-)
     
       This unit depends on the conditional defines `__BP_TYPE_SIZES__',
       `__BP_RANDOM__' and `__BP_PARAMSTR_0__'.
     
       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.
     
       If `__BP_PARAMSTR_0__' is defined (`-D__BP_PARAMSTR_0__'), this
       unit will change the value of `ParamStr (0)' to that of
       `ExecutablePath', overwriting the value actually passed by the
       caller, to imitate BP's/Dos's behaviour. However *note*: On most
       systems, `ExecutablePath' is *not* guaranteed to return the full
       path, so defining this symbol doesn't change anything. In general,
       you *cannot* expect to find the full executable path, so better
       don't even try it, or your program will (at best) run on some
       systems. For most cases where BP programs access their own
       executable, there are cleaner alternatives available.
     
       Copyright (C) 1998-2002 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,I-}
     {$if __GPC_RELEASE__ < 20020225}
     {$error This unit requires GPC release 20020225 or newer.}
     {$endif}
     
     unit System;
     
     interface
     
     import GPC (MaxLongInt => GPC_MaxLongInt);
     
     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}
     
       {$if False}  { @@ doesn't work well (dialec3.pas) -- when GPC gets
       short
                         strings, it will be unnecessary }
       {$ifdef __BORLAND_PASCAL__}
       String = String [255];
       {$endif}
       {$endif}
     
     const
       MaxInt     = High (Integer);
       MaxLongInt = High (LongInt);
     
     { Return the lowest-order byte of x }
     function  Lo (x: LongestInt): Byte; asmname '_p_Lo';
     
     { Return the lowest-but-one-order byte of x }
     function  Hi (x: LongestInt): Byte; asmname '_p_Hi';
     
     { Swap the lowest- and lowest-but-one-order bytes, mask out the
       higher ones }
     function  Swap (x: LongestInt): Word; asmname '_p_Swap';
     
     { Store the current directory name (on the given drive number if
       drive <> 0) in s }
     procedure GetDir (Drive: Byte; var s: String); asmname '_p_GetDir';
     
     { Dummy routine for compatibility. @@Use two overloaded versions
       rather than varargs when possible. }
     procedure SetTextBuf (var f: Text; var Buf; ...);
       asmname '_p_SetTextBuf';
     
     { 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; asmname '_p_Ofs';
     function  Seg (const X): PtrWord; asmname '_p_Seg';
     function  Ptr (Seg, Ofs: PtrWord): Pointer; asmname '_p_Ptr';
     function  CSeg: PtrWord; asmname '_p_CSeg';
     function  DSeg: PtrWord; asmname '_p_DSeg';
     function  SSeg: PtrWord; asmname '_p_SSeg';
     function  SPtr: PtrWord; asmname '_p_SPtr';
     
     { 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; asmname '_p_RealToBPReal';
     function BPRealToReal (const BR: BPReal): Real;
       asmname '_p_BPRealToReal';
     
     { 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;
       asmname '_p_HeapErrorNilReturn';
     
     { 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. What makes these routines unrealiable is, e.g., that on
       multi-tasking systems, another process may allocate memory after
       you've called MemAvail/MaxAvail and before you get to do the next
       allocation. Also, please note that some systems over-commit
       virtual memory which may cause MemAvail to return a value larger
       than the actual (physical plus swap) memory available. Therefore,
       if you want to be "sure" (modulo the above restrictions) that the
       memory is actually available, use MaxAvail. }
     function  MemAvail: Cardinal; asmname '_p_MemAvail';
     function  MaxAvail: Cardinal; asmname '_p_MaxAvail';
     
     { Delphi compatibility }
     
     function  CompToDouble (x: Comp): Double; asmname '_p_CompToDouble';
     function  DoubleToComp (x: Double): Comp; asmname '_p_DoubleToComp';
     function  AllocMemCount: Integer; asmname '_p_AllocMemCount';
     function  AllocMemSize: SizeType; asmname '_p_AllocMemSize';
     procedure Assert (Condition: Boolean); asmname '_p_Assert';
     procedure DefaultAssertErrorProc (const Message, FileName: String;
       LineNumber: Integer; ErrorAddr: Pointer);
       asmname '_p_DefaultAssertErrorProc';
     
     var
       AssertErrorProc: ^procedure (const Message, FileName: String;
       LineNumber: Integer; ErrorAddr: Pointer) =
       @DefaultAssertErrorProc;
       NoErrMsg: Boolean = False;


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 (perhaps by telling the user to
         save the data, then terminate the program and report the bug 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!
     
       - Nested traps are supported, i.e. you can call TrapExec again
         within a routine called by another TrapExec instance. Runtime
         errors trapped within the inner TrapExec invocation will be
         trapped by the inner TrapExec, while runtime errors trapped
         after its termination will be trapped by the outer TrapExec
         again.
     
       Copyright (C) 1996-2002 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,I-}
     
     unit Trap;
     
     interface
     
     uses GPC;
     
     var
       TrappedExitCode: Integer = 0;
       TrappedErrorAddr: Pointer = nil;
       TrappedErrorMessageString: TString = '';
     
     { Trap runtime errors. See the comment at the top. }
     procedure TrapExec (procedure p (Trapped: Boolean));
       asmname '_p_trapexec';
     
     { Forget about saved errors from the innermost TrapExec instance. }
     procedure TrapReset; asmname '_p_trapreset';


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-2002 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,I-}
     {$if __GPC_RELEASE__ < 20020225}
     {$error This unit requires GPC release 20020225 or newer.}
     {$endif}
     
     { @@ Work-around for a problem with COFF debug info. Will hopefully
          disappear with qualified identifiers. }
     {$ifdef DJGPP}
     {$local W-} {$no-debug-info} {$endlocal}
     {$endif}
     
     unit Turbo3;
     
     interface
     
     import GPC;
            System (MemAvail => System_MemAvail,
                    MaxAvail => System_MaxAvail);
            CRT (LowVideo  => CRT_LowVideo,
                 HighVideo => CRT_HighVideo);
     
     var
       Kbd: Text;
       CBreak: Boolean absolute CheckBreak;
     
     procedure AssignKbd (var F: { @@ AnyFile } Text);
     function  MemAvail: Integer; asmname '_p_MemAvail3';
     function  MaxAvail: Integer; asmname '_p_MaxAvail3';
     function  LongFileSize (var F: AnyFile): Real;
     function  LongFilePos  (var F: AnyFile): Real;
     procedure LongSeek     (var F: AnyFile; aPosition: Real);
     procedure LowVideo; asmname '_p_LowVideo3';
     procedure HighVideo; asmname '_p_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 IA32 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 IA32 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-2002 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,I-}
     {$if __GPC_RELEASE__ < 20020225}
     {$error This unit requires GPC release 20020225 or newer.}
     {$endif}
     
     { @@ Work-around for a problem with COFF debug info. Will hopefully
          disappear with qualified identifiers. }
     {$ifdef DJGPP}
     {$local W-} {$no-debug-info} {$endlocal}
     {$endif}
     
     unit WinDos;
     
     interface
     
     import GPC; System; Dos (FCarry     => Dos_FCarry,
                              FParity    => Dos_FParity,
                              FAuxiliary => Dos_FAuxiliary,
                              FZero      => Dos_FZero,
                              FSign      => Dos_FSign,
                              FOverflow  => Dos_FOverflow,
                              DosError   => Dos_DosError,
                              GetCBreak  => Dos_GetCBreak,
                              SetCBreak  => Dos_SetCBreak,
                              GetVerify  => Dos_GetVerify,
                              SetVerify  => Dos_SetVerify,
                              {$ifdef __BP_UNPORTABLE_ROUTINES__}
                              {$ifdef DJGPP}
                              Intr       => Dos_Intr,
                              MsDos      => Dos_MsDos,
                              {$endif}
                              DosVersion => Dos_DosVersion,
                              SetDate    => Dos_SetDate,
                              SetTime    => Dos_SetTime,
                              {$endif}
                              FindFirst  => Dos_FindFirst,
                              FindNext   => Dos_FindNext,
                              FindClose  => Dos_FindClose);
     
     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; asmname '_p_DosError'; external;
     
     procedure GetDate (var Year, Month, Day, DayOfWeek: Word);
       asmname '_p_getdate';
     procedure GetTime (var Hour, Minute, Second, Sec100: Word);
       asmname '_p_gettime';
     procedure GetCBreak (var BreakOn: Boolean); asmname '_p_getcbreak';
     procedure SetCBreak (BreakOn: Boolean); asmname '_p_setcbreak';
     procedure GetVerify (var VerifyOn: Boolean); asmname '_p_getverify';
     procedure SetVerify (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 { @@ anyfile: GPC_AnyFile } ; var Attr:
       TDosAttr); asmname '_p_getfattr';
     procedure SetFAttr (var F { @@ anyfile: GPC_AnyFile } ; Attr:
       TDosAttr); asmname '_p_setfattr';
     procedure GetFTime (var F { @@ anyfile: GPC_AnyFile } ; var aTime:
       LongInt); asmname '_p_getftime';
     procedure SetFTime (var F { @@ anyfile: 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 FindFirst (Path: PChar; Attr: Word; var SR: TSearchRec);
       asmname '_p_wfindfirst';
     procedure FindNext  (var SR: TSearchRec); asmname '_p_wfindnext';
     procedure FindClose (var SR: TSearchRec); asmname '_p_wfindclose';
     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;
       asmname '_p_wfilesearch';
     function  FileExpand (Dest, Name: PChar): PChar;
       asmname '_p_wfileexpand';
     function  FileSplit (Path, Dir, Name, Ext: PChar): Word;
       asmname '_p_wfilesplit';
     function  GetCurDir (Dir: PChar; Drive: Byte): PChar;
       asmname '_p_wgetcurdir';
     procedure SetCurDir (Dir: PChar); asmname '_p_wsetcurdir';
     procedure CreateDir (Dir: PChar); asmname '_p_wcreatedir';
     procedure RemoveDir (Dir: PChar); asmname '_p_wremovedir';
     function  GetArgCount: Integer; asmname '_p_wgetargcount';
     function  GetArgStr (Dest: PChar; ArgIndex: Integer; MaxLen: Word):
       PChar; asmname '_p_wgetargstr';
     function  GetEnvVar (VarName: PChar): PChar;
       asmname '_p_cstringgetenv';
     
     {$ifdef __BP_UNPORTABLE_ROUTINES__}
     {$ifdef DJGPP}
     procedure Intr (IntNo: Byte; var Regs: Registers);
       asmname '_p_intr';
     procedure MsDos (var Regs: Registers); asmname '_p_msdos';
     {$endif}
     function  DosVersion: Word; asmname '_p_dosversion';
     procedure SetDate (Year, Month, Day: Word); asmname '_p_setdate';
     procedure SetTime (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::
* as::
* 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::
* Finalize::
* Flush::
* for::
* FormatString::
* forward::
* Frac::
* FrameAddress::
* FreeMem::
* function::
* GE::
* Get::
* GetMem::
* GetTimeStamp::
* goto::
* GT::
* Halt::
* High::
* if::
* Im::
* implementation::
* import::
* in::
* Inc::
* Include::
* Index::
* inherited::
* Initialize::
* inline::
* InOutRes::
* 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::
* Ord::
* or else::
* or_else::
* otherwise::
* Output::
* Override::
* Pack::
* packed::
* Page::
* PAnsiChar::
* ParamCount::
* ParamStr::
* PChar::
* Pi::
* PObjectType::
* 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 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::.

