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: GPCUtil,  Next: HeapMon,  Prev: GMP,  Up: GPC Units

Turbo Power compatibility, etc.
-------------------------------

   The following listing contains the interface of the GPCUtil unit.

   This unit provides some utility routines for compatibility to some
units available for BP, like some `Turbo Power' units.

     {
     Some utility routines for compatibility to some units available for
     BP, like some `Turbo Power' units.
     
     @@NOTE - SOME OF THE ROUTINES IN THIS UNIT MAY NOT WORK CORRECTLY.
     TEST CAREFULLY AND USE WITH CARE!
     
     Copyright (C) 1998-2000 Free Software Foundation, Inc.
     
     Authors: Prof. Abimbola A. Olowofoyeku <African_Chief@bigfoot.com>
              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 GPCUtil;
     
     interface
     
     uses GPC;
     
     { Replace all occurences of OldC with NewC in s and return the
       result }
     function  ReplaceChar (const s : String; OldC, NewC : Char) :
       TString;
     
     { Return the current working directory }
     function  ThisDirectory : TString;
       asmname '_p_get_current_directory';
     
     { Does a directory exist? }
     function  IsDirectory (const aFileName : String) : Boolean;
       asmname '_p_directory_exists';
     
     { Break a string into 2 parts, using Ch as a marker }
     function  BreakStr (const Src : String; var Dest1, Dest2 : String;
       Ch : Char) : Boolean;
     
     { Convert a CString to an Integer }
     function  PChar2Int (s : CString) : Integer;
     
     { Convert a CString to a LongInt }
     function  PChar2Long (s : CString) : LongInt;
     
     { Convert a CString to a Double }
     function  PChar2Double (s : CString) : Double;
     
     { Search for s as an executable in the path and return its location
       (full pathname) }
     function  PathLocate (const s : String) : TString;
     
     { Copy file Src to Dest and return the number of bytes written }
     function  CopyFile (const Src, Dest : String; BufSize : Integer) :
       LongInt;
     
     { Copy file Src to Dest and return the number of bytes written;
       report the number of bytes written versus total size of the source
       file }
     function  CopyFileEx (const Src, Dest : String; BufSize : Integer;
       function Report (Reached, Total : LongInt) : LongInt) : LongInt;
     
     { Turbo Power compatibility }
     
     { Execute the program prog. Dummy1 and Dummy2 are for compatibility
       only; they are ignored. }
     function  ExecDos (const Prog : String; Dummy1 : Boolean; Dummy2 :
       Pointer) : Integer;
     
     { Return whether Src exists in the path as an executable -- if so
       return its full location in Dest }
     function  ExistOnPath (const Src : String; var Dest : String) :
       Boolean;
     
     { Does file name s exist? }
     function  ExistFile (const aFileName : String) : Boolean;
       asmname '_p_file_exists';
     
     { Return just the directory path of Path. Returns DirSelf +
       DirSeparator if Path contains no directory. }
     function  JustPathName (const Path : String) : TString;
       asmname '_p_dir_from_path';
     
     { Return just the file name part without extension of Path. Empty if
       Path contains no file name. }
     function  JustFileName (const Path : String) : TString;
       asmname '_p_name_from_path';
     
     { Return just the extension of Path. Empty if Path contains no
       extension. }
     function  JustExtension (const Path : String) : TString;
       asmname '_p_ext_from_path';
     
     { Change the extension of s to Ext (do not include the dot!) }
     function  ForceExtension (const s, Ext : String) : TString;
     
     { Return the full pathname of Path }
     function  FullPathName (const Path : String) : TString;
       asmname '_p_fexpand';
     
     { Add a DirSeparator to the end of s if there is not already one }
     function  AddBackSlash (const s : String) : TString;
       asmname '_p_forceadddirseparator';
     
     { Convert Integer to PChar; uses CStringNew to allocate memory for
       the result, so you must call StrDispose to free the memory later }
     function  Int2PChar (i : Integer) : PChar;
     
     { Convert Integer to string }
     function  Int2Str (i : Integer) : TString;
     
     { Convert string to Integer }
     function  Str2Int (const s : String; var i : Integer) : Boolean;
     
     { Convert string to LongInt }
     function  Str2Long (const s : String; var i : LongInt) : Boolean;
     
     { Convert string to Double }
     function  Str2Real (const s : String; var i : Double) : Boolean;
     
     { Return a string stripped of leading spaces }
     function  TrimLead (const s : String) : TString;
       asmname '_p_trimleft_str';
     
     { Return a string stripped of trailing spaces }
     function  TrimTrail (const s : String) : TString;
       asmname '_p_trimright_str';
     
     { Return a string stripped of leading and trailing spaces }
     function  Trim (const s : String) : TString;
       asmname '_p_trimboth_str';
     
     { Return a string right-padded to length Len with ch }
     function  PadCh (const s : String; ch : Char; Len : Integer) :
       TString;
     
     { Return a string right-padded to length Len with spaces }
     function  Pad (const s : String; Len : Integer) : TString;
     
     { Return a string left-padded to length Len with ch }
     function  LeftPadCh (const s : String; ch : Char; Len : Byte) :
       TString;
     
     { Return a string left-padded to length Len with blanks }
     function  LeftPad (const s : String; Len : Integer) : TString;
     
     { Convert a string to lowercase }
     function  StLoCase (const s : String) : TString;
       asmname '_p_locase_str';
     
     { Convert a string to uppercase }
     function  StUpCase (const s : String) : TString;
       asmname '_p_upcase_str';
     
     { Uniform access to big memory blocks for GPC and BP. Of course, for
       programs that are meant only for GPC, you can use the usual
       New/Dispose
       routines. But for programs that should compile with GPC and BP,
       you can
       use the following routines for GPC. In the GPC unit for BP
       (gpc-bp.pas),
       you can find emulations for BP that try to provide access to as
       much
       memory as possible, despite the limitations of BP. The backdraw is
       that
       this memory cannot be used freely, but only with the following
       moving
       routines. }
     
     type
       PBigMem = ^TBigMem;
       TBigMem (MaxNumber : Integer) = record
         { Public fields }
         Number, BlockSize : SizeType;
         Mappable : Boolean;
         { Private fields }
         Pointers : array [1 .. MaxNumber] of ^Byte
       end;
     
     { Note: the number of blocks actually allocated may be smaller than
       WantedNumber. Check the Number field of the result. }
     function  AllocateBigMem (WantedNumber, aBlockSize : SizeType;
       WantMappable : Boolean) : PBigMem;
     procedure DisposeBigMem (p : PBigMem);
     procedure MoveToBigMem (var Source; p : PBigMem; BlockNumber :
       SizeType);
     procedure MoveFromBigMem (p : PBigMem; BlockNumber : SizeType; var
       Dest);
     { Maps a big memory block into normal addressable memory and returns
       its address. The memory must have been allocated with
       WantMappable = True. The mapping is only valid until the next
       MapBigMem call. }
     function  MapBigMem (p : PBigMem; BlockNumber : SizeType) : Pointer;


File: gpc.info,  Node: HeapMon,  Next: MD5,  Prev: GPCUtil,  Up: GPC Units

Primitive heap checking
-----------------------

   The following listing contains the interface of the HeapMon unit.

   This unit provide a rather primitive means to watch the heap, i.e.
check if all pointers that were allocated are released again. This is
meant as a debugging help for avoiding memory leaks.

   More extensive heap checking is provided by libraries like `efence'
which can be used in GPC programs without special provisions.

     {
     A unit to watch the heap, i.e. check if all pointers that were
     allocated are released again. This is meant as a debugging help
     for avoiding memory leaks.
     
     Use it in the main program before all other units. When, at the
     end of the program, some pointers that were allocated, have not
     been released, the unit prints a message to StdErr. Only pointers
     allocated via the Pascal mechanisms (New, GetMem) are tracked, not
     pointers allocated with direct libc calls or from C code. After a
     runtime error, pointers are not checked.
     
     Note that many units and libraries allocate memory for their own
     purposes and don't always release it at the end. Therefore, the
     usefulness of this unit is rather limited.
     
     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 HeapMon;
     
     interface
     
     uses GPC;
     
     { This unit has an empty interface. It is automatically activated
       when used. }


File: gpc.info,  Node: MD5,  Next: Overlay,  Prev: HeapMon,  Up: GPC Units

`MD5' Message Digests
---------------------

   The following listing contains the interface of the MD5 unit.

   This unit provides functions to compute `MD5' message digest of
files or memory blocks, according to the definition of `MD5' in `RFC
1321' from April 1992.

     {
     Functions to compute MD5 message digest of files or memory blocks,
     according to the definition of MD5 in RFC 1321 from April 1992.
     
     IMPORTANT NOTE: This unit is distributed under the GNU GPL, NOT
     under the GNU LGPL under which most of the other GPC units are
     distributed. This means that you must distribute any code that
     uses this unit under the GPL as well, which means that you have to
     make the source code available whenever you distribute a binary of
     the code, and that you must allow recipients to modify the code
     and redistribute it under the GPL.
     
     Copyright (C) 1995, 1996, 2000 Free Software Foundation, Inc.
     
     Based on the C code written by Ulrich Drepper
     <drepper@gnu.ai.mit.edu>, 1995 as part of the GNU C Library.
     
     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.
     }
     
     {$gnu-pascal}
     {$if __GPC_RELEASE__ < 20000412}
     {$error This unit requires GPC release 20000412 or newer.}
     {$endif}
     
     unit MD5;
     
     interface
     
     uses GPC;
     
     { Representation of a MD5 value. It is always in little endian byte
       order and therefore portable. }
     type
       Card8 = Cardinal (8);
       TMD5 = array [1 .. 16] of Card8;
     
     { Computes MD5 message digest for Length bytes in Buffer. }
     procedure MD5Buffer (const Buffer; Length : SizeType; var MD5 :
       TMD5); asmname '_p_md5_buffer';
     
     { Computes MD5 message digest for the contents of the file f. }
     (*@@iocritical*)procedure MD5File (var f : File; var MD5 : TMD5);
       asmname '_p_md5_file';
     
     { Initializes a MD5 value with zeros. }
     procedure MD5Clear (var MD5 : TMD5); asmname '_p_md5_clear';
     
     { Compares two MD5 values for equality. }
     function MD5Compare (const Value1, Value2 : TMD5) : Boolean;
       asmname '_p_md5_compare';
     
     { Converts an MD5 value to a string. }
     function MD5Str ((*@@fjf382 const*) MD5 : TMD5) = s : TString;
       asmname '_p_md5_str';
     
     { Converts a string to an MD5 value. Returns True if successful. }
     function MD5Val (const s : String; var MD5 : TMD5) : Boolean;
       asmname '_p_md5_val';
     
     { Composes two MD5 values to a single one. }
     function MD5Compose (const Value1, Value2 : TMD5) = Dest : TMD5;
       asmname '_p_md5_compose';


File: gpc.info,  Node: Overlay,  Next: Pipe,  Prev: MD5,  Up: GPC Units

BP compatibility: Overlay
-------------------------

   The following listing contains the interface of the Overlay unit.

   This is just a dummy replacement for BP's `Overlay' unit, since GPC
doesn't need overlays.

     {
     Dummy BP compatible overlay unit for GPC
     
     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 Overlay;
     
     interface
     
     const
       ovrOk = 0;
       ovrError = - 1;
       ovrNotFound = - 2;
       ovrNoMemory = - 3;
       ovrIOError = - 4;
       ovrNoEMSDriver = - 5;
       ovrNoEMSMemory = - 6;
     
     const
       OvrEmsPages  : Word = 0;
       OvrTrapCount : Word = 0;
       OvrLoadCount : Word = 0;
       OvrFileMode  : Byte = 0;
     
     type
       OvrReadFunc = function (OvrSeg : Word) : Integer;
     
     var
       OvrReadBuf : OvrReadFunc;
       OvrResult  : Integer = 0;
     
     procedure OvrInit (aFileName : String);
     procedure OvrInitEMS;
     procedure OvrSetBuf (Size : LongInt);
     function  OvrGetBuf : LongInt;
     procedure OvrSetRetry (Size : LongInt);
     function  OvrGetRetry : LongInt;
     procedure OvrClearBuf;


File: gpc.info,  Node: Pipe,  Next: Ports,  Prev: Overlay,  Up: GPC Units

Start a child process, connected with pipes, also on Dos
--------------------------------------------------------

   The following listing contains the interface of the Pipe unit.

   This unit provides routines to start a child process and write
to/read from its Input/Output/StdErr via pipes. All of this is emulated
transparently under Dos as far as possible.

     {
     Piping data from and to processes and process signaling
     
     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}
     
     { Keep this consistent with the one in pipec.c }
     {$if defined(MSDOS) or defined(__MINGW32__)}
     {$define NOFORK}
     {$endif}
     
     unit Pipe;
     
     interface
     
     uses GPC;
     
     (*$local W-*)type PPStrings = ^TPStrings;TPStrings (Count: Cardinal)
       = array [1 .. Count] of ^String; (*@@two unit bug with definition
       in gpc.pas in programs using these two units*) (*$endlocal*)
     
     const
       PipeForking = {$ifdef NOFORK} False {$else} True {$endif};
     
     type
       TProcedure = procedure;
     
       PWaitPIDResult = ^TWaitPIDResult;
       TWaitPIDResult = (PIDNothing, PIDExited, PIDSignaled, PIDStopped,
       PIDUnknown);
     
       PPipeProcess = ^TPipeProcess;
       TPipeProcess = record
         PID       : Integer;        { Process ID of process forked }
         SignalPID : Integer;        { Process ID to send the signal to.
                                       Equals PID by default }
         OpenPipes : Integer;        { Number of pipes to/from the
                                       process, for internal use }
         Signal    : Integer;        { Send this signal (if not 0) to the
                                       process after all pipes have been
                                       closed after some time }
         Seconds   : Integer;        { Wait so many seconds before
                                       sending the signal if the process
                                       has not terminated by itself }
         Wait      : Boolean;        { Wait for the process, even longer
                                       than Seconds seconds, after
                                       sending the signal (if any) }
         Result    : PWaitPIDResult; { Default nil. If a pointer to a
                                       variable is stored here, its
                                       destination will contain the
                                       information whether the process
                                       terminated by itself, or was
                                       terminated or stopped by a signal,
                                       when waiting after closing the
                                       pipes }
         Status    : ^Integer;       { Default nil. If a pointer to a
                                       variable is stored here, its
                                       destination will contain the exit
                                       status if the process terminated
                                       by itself, or the number of the
                                       signal otherwise, when waiting
                                       after closing the pipes }
       end;
     
     const
       EFork  = 600; { cannot fork `%s'' }
       ESpawn = 601; { cannot spawn `%s'' }
     
     var
       { Default values for TPipeProcess records created by Pipe }
       DefaultPipeSignal  : Integer = 0;
       DefaultPipeSeconds : Integer = 0;
       DefaultPipeWait    : Boolean = True;
     
     {
       The procedure Pipe starts a process whose name is given by
       ProcessName, with the given parameters (can be null if no
       parameters) and environment, and create pipes from and/or to the
       process' standard input/output/error. ProcessName is searched for
       in the PATH with FSearchExecutable. Any of ToInputFile,
       FromOutputFile and FromStdErrFile can be null if the corresponding
       pipe is not wanted. FromOutputFile and FromStdErrFile may be
       identical, in which case standard output and standard error are
       redirected to the same pipe. The behaviour of other pairs of files
       being identical is undefined, and useless, anyway. The files are
       Assigned and Reset or Rewritten as appropriate. Errors are
       returned in IOResult. If Process is not null, a pointer to a
       record is stored there, from which the PID of the process created
       can be read, and by writing to which the action after all pipes
       have been closed can be changed. (The record is automatically
       Dispose'd of after all pipes have been closed.) If automatic
       waiting is turned off, the caller should get the PID from the
       record before it's Dispose'd of, and wait for the process sometime
       in order to avoid zombies. If no redirections are performed (i.e.,
       all 3 files are null), the caller should wait for the process with
       WaitPipeProcess. When an error occurs, Process is not assigned to,
       and the state of the files is undefined, so be sure to check
       IOResult before going on.
     
       ChildProc, if not nil, is called in the child process after
       forking and redirecting I/O, but before executing the new process.
       It can even be called instead of executing a new process
       (ProcessName can be empty then).
     
       The procedure even works under Dos, but, of course, in a limited
       sense: if ToInputFile is used, the process will not actually be
       started until ToInputFile is closed. Signal, Seconds and Wait of
       TPipeProcess are ignored, and PID and SignalPID do not contain a
       Process ID, but an internal value without any meaning to the
       caller. Result will always be PIDExited. So, Status is the only
       interesting field (but Result should also be checked). Since there
       is no forking under Dos, ChildProc, if not nil, is called in the
       main process before spawning the program. So, to be portable, it
       should not do any things that would influence the process after
       the return of the Pipe function.
     
       The only portable way to use "pipes" in both directions is to call
       `Pipe', write all the Input data to ToInputFile, close
       ToInputFile, and then read the Output and StdErr data from
       FromOutputFile and FromStdErrFile. However, since the capacity of
       pipes is limited, one should also check for Data from
       FromOutputFile and FromStdErrFile (using CanRead, IOSelect or
       IOSelectRead) while writing the Input data (under Dos, there
       simply won't be any data then, but checking for data doesn't do
       any harm). Please see pipedemo.pas for an example.
     }
     (*@@IO critical*) procedure Pipe (var ToInputFile, FromOutputFile,
       FromStdErrFile : AnyFile; (*@@fjf265 const*) ProcessName : String;
       protected var Parameters : TPStrings; ProcessEnvironment :
       PCStrings; var Process : PPipeProcess; ChildProc : TProcedure);
     
     {
       Waits for a process created by Pipe as determined in the Process
       record. (Process is Dispose'd of afterwards.) Returns True if
       successful.
     }
     function WaitPipeProcess (Process : PPipeProcess) : Boolean;


File: gpc.info,  Node: Ports,  Next: Printer,  Prev: Pipe,  Up: GPC Units

BP compatibility (partly): `Port', `PortW' arrays
-------------------------------------------------

   The following listing contains the interface of the Ports unit.

   This unit provides access routines for the hardware ports on the
x86, as a partial replacement for BP's `Port' and `PortW' pseudo arrays.

   Since port access is platform-specific, this unit cannot be used in
code intended to be portable. Even on the x86, its use can often be
avoided - e.g. Linux provides a number of `ioctl' functions, and DJGPP
provides some routines to achieve things that would require port access
under BP. Therefore, it is recommended to avoid using this unit
whenever possible.

     {
     Access functions for I/O ports for GPC on an x86 platform. This unit
     is *not* portable. It works only on x86 platforms (tested under
       Linux
     and DJGPP). It is provided here only to serve as a replacement for
     BP's Port and PortW pseudo arrays.
     
     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}
     {$ifndef __i386__}
     {$error The Ports unit is only for the x86 platform}
     {$endif}
     
     unit Ports;
     
     interface
     
     { Port access functions }
     function  InPortB  (PortNumber : ShortWord) : Byte;
     function  InPortW  (PortNumber : ShortWord) : ShortWord;
     procedure OutPortB (PortNumber : ShortWord; aValue : Byte);
     procedure OutPortW (PortNumber, aValue : ShortWord);
     
     { libc functions for getting access to the ports -- only for root
       processes, of course -- and to give up root privileges after
       getting access to the ports for setuid root programs. Dummies
       under DJGPP. }
     function  IOPerm (From, Num : MedCard; On : Integer) : Integer;
       asmname 'ioperm';
     function  IOPL (Level : Integer) : Integer; asmname 'iopl';
     function  SetEUID (EUID : Integer) : Integer; asmname 'seteuid';


File: gpc.info,  Node: Printer,  Next: RegEx,  Prev: Ports,  Up: GPC Units

BP compatibility: Printer, portable
-----------------------------------

   The following listing contains the interface of the Printer unit.

   This unit provides printer access, compatible to BP's `Printer'
unit, for Dos (using printer devices) and Unix systems (using printer
utilities).

   For BP compatibility, the variable `Lst' is provided, but for newly
written programs, it is recommended to use the `AssignPrinter'
procedure on a text file, and close the file when done (thereby
committing the printer job). This method allows for sending multiple
printer jobs in the same program.

     {
     BP compatible printer unit with extensions
     
     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 Printer;
     
     interface
     
     {$ifdef __OS_DOS__}
     
     { Dos-like systems: writing to a printer device }
     
     uses GPC;
     
     var
       { The file name to write printer output into }
       PrinterDeviceName : ^String = @'prn';
     
     {$else}
     
     { Unix-like systems: printing via a printer program }
     
     uses GPC, Pipe;
     
     const
       EPrinterRead = 610; { printer can only be opened for writing }
     
     var
       { The file name of the printer program. If it contains a '/', it
         will be taken as a complete path, otherwise the file name will
         be searched for in the PATH with FSearchExecutable. }
       PrinterCommand : ^String = @'lpr';
     
       { Optional command line parameters for the printer program.
         Ignored when nil. }
       PrinterArguments : ^TPStrings = nil;
     
       { How to deal with the printer spooler after the printer pipe is
         closed, cf. the Pipe unit. }
       PrinterPipeSignal  : Integer = 0;
       PrinterPipeSeconds : Integer = 0;
       PrinterPipeWait    : Boolean = True;
     
     {$endif}
     
     { Text file opened to default printer }
     var
       Lst : Text;
     
     { Assign a file to the printer. Lst will be assigned to the default
       printer at program start, but other files can be assigned to the
       same or other printers (possibly after changing the variables
       above). SpoolerOutput, if not null, will be redirected from the
       printer spooler's standard output and error. If you use this, note
       that a deadlock might arise when trying to write data to the
       spooler while its output is not being read, though this seems
       quite unlikely, since most printer spoolers don't write so much
       output that could fill a pipe. Under Dos, where no spooler is
       involved, SpoolerOutput, if not null, will be reset to an empty
       file for compatibility. }
     procedure AssignPrinter (var f : AnyFile; var SpoolerOutput :
       AnyFile);


File: gpc.info,  Node: RegEx,  Next: Strings,  Prev: Printer,  Up: GPC Units

Regular Expression matching and substituting
--------------------------------------------

   The following listing contains the interface of the RegEx unit.

   This unit provides routines to match strings against regular
expressions and perform substitutions using matched subexpressions.
Regular expressions are strings with some characters having special
meanings. They describe (match) a class of strings. They are similar to
wild cards used in file name matching, but much more powerful.

   To use this unit, you will need the `rx' library which can be found
in `ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/libs/'.

     {$nested-comments}
     {
     Regular expression matching and replacement
     
     The RegEx unit provides routines to match strings against regular
     expressions and perform substitutions using matched subexpressions.
     
     To use the RegEx unit, you will need the rx library which can be
     found in ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/libs/ .
     
     Regular expressions are strings with some characters having special
     meanings. They describe (match) a class of strings. They are similar
     to wild cards used in file name matching, but much more powerful.
     
     There are two kinds of regular expressions supported by this unit,
     basic and extended regular expressions. The difference between them
     is not functionality, but only syntax. The following is a short
     overview of regular expressions. For a more thorough explanation see
     the literature, or the documentation of the rx library, or man pages
     of programs like grep(1) and sed(1).
     
     Basic           Extended        Meaning
     `.'             `.'             matches any single character
     `[aei-z]'       `[aei-z]'       matches either `a', `e', or any
                                     character from `i' to `z'
     `[^aei-z]'      `[^aei-z]'      matches any character but `a', `e',
                                     or `i' .. `z'
                                     To include in such a list the the
                                     characters `]', `^', or `-', put
                                     them first, anywhere but first, or
                                     first or last, resp.
     `[[:alnum:]]'   `[[:alnum:]]'   matches any alphanumeric character
     `[^[:digit:]]'  `[^[:digit:]]'  matches anything but a digit
     `[a[:space:]]'  `[a[:space:]]'  matches the letter `a' or a space
                                     character (space, tab)
     ...                             (there are more classes available)
     `\w'            `\w'            = [[:alnum:]]
     `\W'            `\W'            = [^[:alnum:]]
     `^'             `^'             matches the empty string at the
                                     beginning of a line
     `$'             `$'             matches the empty string at the end
                                     of a line
     `*'             `*'             matches zero or more occurences of
                                     the preceding expression
     `\+'            `+'             matches one or more occurences of
                                     the preceding expression
     `\?'            `?'             matches zero or one occurence of the
                                     preceding expression
     `\{N\}'         `{N}'           matches exactly N occurences of the
                                     preceding expression (N is an
                                     integer number)
     `\{M,N\}'       `{M,N}'         matches M to N occurences of the
                                     preceding expression (M and N are
                                     integer numbers, M <= N)
     `A B'           `A B'           matches A followed by B (A and B are
                                     regular expressions)
     `A\|B'          `A|B'           matches A or B (A and B are regular
                                     expressions)
     `\( \)'         `( )'           forms a subexpression, to override
                                     precedence, and for subexpression
                                     references
     `\7'            `\7'            matches the 7'th parenthesized
                                     subexpression (counted by their
                                     start in the regex), where 7 is a
                                     number from 1 to 9 ;-).
                                     *Please note:* using this feature
                                     can be *very* slow or take very much
                                     memory (exponential time and space
                                     in the worst case, if you know what
                                     that means...).
     `\'             `\'             quotes the following character if
                                     it's special (i.e. listed above)
     rest            rest            any other character matches itself
     
     Precedence, from highest to lowest:
     * parentheses (`()')
     * repetition (`*', `+', `?', `{}')
     * concatenation
     * alternation (`|')
     
     When performing substitutions using matched subexpressions of a
     regular expression (see `ReplaceSubExpressionReferences'), the
     replacement string can reference the whole matched expression with
     `&' or `\0', the 7th subexpression with `\7' (just like in the regex
     itself, but using it in replacements is not slow), and the 7th
     subexpression converted to upper/lower case with `\u7' or `\l7',
     resp. (which also works for the whole matched expression with `\u0'
     or `\l0'). A verbatim `&' or `\' can be specified with `\&' or `\\',
     resp.
     
     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.
     
     Please also note the license of the rx library.
     }
     
     {$gnu-pascal}
     {$if __GPC_RELEASE__ < 20000412}
     {$error This unit requires GPC release 20000412 or newer.}
     {$endif}
     
     unit RegEx;
     
     interface
     
     uses GPC;
     
     const
       { `BasicRegExSpecialChars' contains all characters that have
         special meanings in basic regular expressions.
         `ExtRegExSpecialChars' contains those that have special meanings
         in extended regular expressions. }
       BasicRegExSpecialChars = ['.', '[', ']', '^', '$', '*', '\'];
       ExtRegExSpecialChars   =
       ['.', '[', ']', '^', '$', '*', '+', '?', '{', '}', '|', '(', ')', '\'];
     
     type
       { The type used by the routines of the `RegEx' unit to store
         regular expressions in an internal format. The fields RegEx,
         RegMatch, ErrorInternal, From and Length are only used
         internally. SubExpressions can be read after `NewRegEx' and will
         contain the number of parenthesized subexpressions. Error should
         be checked after `NewRegEx'. It will be `nil' when it succeeded,
         and contain an error message otherwise. }
       RegExType = record
         RegEx, RegMatch : Pointer;  { Internal }
         ErrorInternal : CString;    { Internal }
         From, Length : Integer;     { Internal }
         SubExpressions : Integer;
         Error : PString
       end;
     
     { Simple interface to regular expression mathing. Matches a regular
       expression against a string starting from a specified position.
       Returns the position of the first match, or 0 if it does not
       match, or the regular expression is invalid. }
     function  RegExPosFrom (const Expression : String; ExtendedRegEx,
       CaseInsensitive : Boolean; const s : String; From : Integer) :
       Integer; asmname '_p_regexposfrom';
     
     { Creates the internal format of a regular expression. If
       ExtendedRegEx is True, Expression is assumed to denote an extended
       regular expression, otherwise a basic regular expression.
       CaseInsensitive determines if the case of letters will be ignored
       when mathing the expression. If NewLines is True, `NewLine'
       characters in a string matched against the expression will be
       treated as dividing the string in multiple lines, so that `$' can
       match before the NewLine and `^' can match after. Also, `.' and
       `[^...]' will not match a NewLine then.}
     procedure NewRegEx (var RegEx : RegExType; const Expression :
       String; ExtendedRegEx, CaseInsensitive, NewLines : Boolean);
       asmname '_p_newregex';
     
     { Disposes of a regular expression created with `NewRegEx'. *Must*
       be used after `NewRegEx' before the RegEx variable becomes invalid
       (i.e., goes out of scope or a pointer pointing to it is Dispose'd
       of). }
     procedure DisposeRegEx (var RegEx : RegExType);
       asmname '_p_dispose_regex';
     
     { Matches a regular expression created with `NewRegEx' against a
       string. }
     function  MatchRegEx (var RegEx : RegExType; const s : String;
       NotBeginningOfLine, NotEndOfLine : Boolean) : Boolean;
       asmname '_p_matchregex';
     
     { Matches a regular expression created with `NewRegEx' against a
       string, starting from a specified position. }
     function  MatchRegExFrom (var RegEx : RegExType; const s : String;
       NotBeginningOfLine, NotEndOfLine : Boolean; From : Integer) :
       Boolean; asmname '_p_matchregexfrom';
     
     { Finds out where the regular expression matched, if `MatchRegEx' or
       `MatchRegExFrom' were successful. If n = 0, it returns the
       position of the whole match, otherwise the position of the n'th
       parenthesized subexpression. MatchPosition and MatchLength will
       contain the position (counted from 1) and length of the match, or
       0 if it didn't match. (Note: MatchLength can also be 0 for a
       successful empty match, so check MatchPosition for 0 to find out
       if it matched at all.) MatchPosition or MatchLength may be null
       and is ignored then. }
     procedure GetMatchRegEx (var RegEx : RegExType; n : Integer; var
       MatchPosition, MatchLength : Integer);
       asmname '_p_getmatch_regex';
     
     { Checks if the string s contains any quoted characters or
       (sub)expression references to the regular expression RegEx created
       with `NewRegEx'. These are `&' or `\0' for the whole matched
       expression (if OnlySub is not set) and `\1' .. `\9' for the n'th
       parenthesized subexpression. Returns 0 if it does not contain any,
       and the number of references and quoted characters if it does. If
       an invalid reference (i.e. a number bigger than the number of
       subexpressions in RegEx) is found, it returns the negative value
       of the (first) invalid reference. }
     function  FindSubExpressionReferences (var RegEx : RegExType; const
       s : String; OnlySub : Boolean) : Integer;
       asmname '_p_find_subexpressionreferences_regex';
     
     { Replaces (sub)expression references in ReplaceStr by the actual
       (sub)expressions and unquotes quoted characters. To be used after
       the regular expression RegEx created with `NewRegEx' was matched
       against s successfully with `MatchRegEx' or `MatchRegExFrom'. }
     function  ReplaceSubExpressionReferences (var RegEx : RegExType;
       const s, ReplaceStr : String) : TString;
       asmname '_p_replace_subexpressionreferences_regex';
     
     { Returns the string for a regular expression that matches exactly
       one character out of the given set. It can be combined with the
       usual operators to form more complex expressions. }
     function  CharSet2RegEx (const Characters : CharSet) : TString;
       asmname '_p_CharSet2RegEx';

