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

Internationalization
--------------------

   The following listing contains the interface of the Intl unit.

   This unit provides national language support via locales and `.mo'
files.

     { Welcome to the wonderful world of
       INTERNATIONALIZATION (i18n).
     
       This unit provides the powerful mechanism of national language
       support by accessing `.mo' files and locale information.
     
       It includes:
         locales (not xlocales) and libintl.
     
       See documentation for gettext (`info gettext') for details.
     
       Because GPC can deal with both CStrings and Pascal Strings, there
       is an interface for both types of arguments and function results
       with slightly different names.
     
       E.g. for Pascal strings:
     
         function GetText (const MsgId: String): TString;
     
       And the same as above, but with a C interface:
     
         function GetTextC (MsgId: CString): CString;
     
       `PLConv' in Pascal is very different from `struct lconv *' in C.
       Element names do not have underscores and have sometimes different
       sizes. The conversion is done automatically and has correct
       results.
     
       Furthermore, we have a tool similar to `xgettext' to extract all
       strings out of a Pascal source. It extracts the strings and writes
       a complete `.po' file to a file. See
       http://www.gnu-pascal.de/contrib/eike/
       The filename is pas2po-VERSION.tar.gz.
     
       Copyright (C) 2001-2002 by Eike Lange
     
       Author: Eike Lange <eike.lange@uni-essen.de>
     
       This unit is free software; you can redistribute it and/or modify
       it under the terms of the GNU Library General Public License as
       published by the Free Software Foundation, version 2.
     
       This unit is distributed in the hope that it will be useful, but
       WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
       Library General Public License for more details.
     
       You should have received a copy of the GNU Library General Public
       License along with this library; see the file COPYING.LIB. If not,
       write to the Free Software Foundation, Inc., 59 Temple Place -
       Suite 330, Boston, MA 02111-1307, USA. }
     
     {$gnu-pascal,I-}
     
     unit Intl;
     
     interface
     
     uses GPC;
     
     type
       IntlString = String (16);
     
       { Port from _p_lconv in intlc.c }
       PLConv = ^TLConv;
       TLConv = record
         { Numeric (non-monetary) information. }
     
         { Decimal point character. }
         DecimalPoint: IntlString;
     
         { Thousands separator. }
         ThousandsSep: IntlString;
     
         { Each element is the number of digits in each group;
           elements with higher indices are farther left.
           An element with value CharMax means that no further grouping
           is done.
           An element with value Chr (0) means that the previous element
           is used for all groups farther left. }
         Grouping: IntlString;
     
         { Monetary information. }
     
         { First three chars are a currency symbol from ISO 4217.
           Fourth char is the separator.  Fifth char is Chr (0). }
         IntCurrSymbol: IntlString;
     
         { Local currency symbol. }
         CurrencySymbol: IntlString;
     
         { Decimal point character. }
         MonDecimalPoint: IntlString;
     
         { Thousands separator. }
         MonThousandsSep: IntlString;
     
         { Like `Grouping' element (above). }
         MonGrouping: IntlString;
     
         { Sign for positive values. }
         PositiveSign: IntlString;
     
         { Sign for negative values. }
         NegativeSign: IntlString;
     
         { Int'l fractional digits. }
         IntFracDigits: ByteInt;
     
         { Local fractional digits. }
         FracDigits: ByteInt;
     
         { 1 if CurrencySymbol precedes a positive value, 0 if it
           succeeds. }
         PCSPrecedes: ByteInt;
     
         { 1 iff a space separates CurrencySymbol from a positive
           value. }
         PSepBySpace: ByteInt;
     
         { 1 if CurrencySymbol precedes a negative value, 0 if it
           succeeds. }
         NCSPrecedes: ByteInt;
     
         { 1 iff a space separates CurrencySymbol from a negative
           value. }
         NSepBySpace: ByteInt;
     
         { Positive and negative sign positions:
           0 Parentheses surround the quantity and CurrencySymbol.
           1 The sign string precedes the quantity and CurrencySymbol.
           2 The sign string follows the quantity and CurrencySymbol.
           3 The sign string immediately precedes the CurrencySymbol.
           4 The sign string immediately follows the CurrencySymbol. }
         PSignPosn,
         NSignPosn: ByteInt;
       end;
     
     { Please do not assign anything to these identifiers! }
     var
       LC_CTYPE:    Integer; asmname '_p_LC_CTYPE';    external;
       LC_NUMERIC:  Integer; asmname '_p_LC_NUMERIC';  external;
       LC_TIME:     Integer; asmname '_p_LC_TIME';     external;
       LC_COLLATE:  Integer; asmname '_p_LC_COLLATE';  external;
       LC_MONETARY: Integer; asmname '_p_LC_MONETARY'; external;
       LC_MESSAGES: Integer; asmname '_p_LC_MESSAGES'; external;
       LC_ALL:      Integer; asmname '_p_LC_ALL';      external;
       CharMax:     Char; asmname '_p_CHAR_MAX';    external;
     
     {@section Locales }
     
     { Set and/or return the current locale. }
     function SetLocale (Category: Integer; const Locale: String):
       TString;
     
     { Set and/or return the current locale. Same as above, but returns
       a CString. }
     function SetLocaleC (Category: Integer; const Locale: String):
       CString;
     
     { Return the numeric/monetary information for the current locale.
       The result is allocated from the heap. You can Dispose it when
       you don't need it anymore. }
     function LocaleConv: PLConv;
     
     {@section GetText }
     
     { Look up MsgId in the current default message catalog for the
       current LC_MESSAGES locale.  If not found, returns MsgId itself
       (the default text). }
     function GetText (const MsgId: String): TString;
     
     { Same as above, but with a C interface }
     function GetTextC (MsgId: CString): CString;
     
     { Look up MsgId in the DomainName message catalog for the current
       LC_MESSAGES locale. }
     function DGetText (const DomainName, MsgId: String): TString;
     
     { Same as above, but with a C interface }
     function DGetTextC (DomainName, MsgId: CString): CString;
     
     { Look up MsgId in the DomainName message catalog for the current
       Category locale. }
     function DCGetText (const DomainName, MsgId: String; Category:
       Integer): TString;
     
     { Same as above, but with a C interface }
     function DCGetTextC (DomainName, MsgId: CString; Category: Integer):
       CString;
     
     { Set the current default message catalog to DomainName.
       If DomainName is empty, reset to the default of `messages'. }
     function TextDomain (const DomainName: String): TString;
     
     { Same as above, but with a C interface.
       If DomainName is nil, return the current default. }
     function TextDomainC (DomainName: CString): CString;
     
     { Specify that the DomainName message catalog will be found
       in DirName rather than in the system locale data base. }
     function BindTextDomain (const DomainName, DirName: String):
       TString;
     
     { Same as above, but with a C interface }
     function BindTextDomainC (DomainName, DirName: CString): CString;


File: gpc.info,  Node: MD5,  Next: Overlay,  Prev: Intl,  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-2002 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,I-}
     {$if __GPC_RELEASE__ < 20001023}
     {$error This unit requires GPC release 20001023 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-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 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
     
       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__ < 20011202}
     {$error This unit requires GPC release 20011202 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;
     
     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;
     
     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; 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;
     
     { Alternative interface from PExecute }
     
     const
       PExecute_First   = 1;
       PExecute_Last    = 2;
       PExecute_One     = PExecute_First or PExecute_Last;
       PExecute_Search  = 4;
       PExecute_Verbose = 8;
     
     { PExecute: execute a chain of processes.
     
       Program and Arguments are the arguments to execv/execvp.
     
       Flags and PExecute_Search is non-zero if $PATH should be searched.
       Flags and PExecute_First is nonzero for the first process in
       chain. Flags and PExecute_Last is nonzero for the last process in
       chain.
     
       The result is the pid on systems like Unix where we fork/exec and
       on systems like MS-Windows and OS2 where we use spawn. It is up to
       the caller to wait for the child.
     
       The result is the exit code on systems like MSDOS where we spawn
       and wait for the child here.
     
       Upon failure, ErrMsg is set to the text of the error message,
       and -1 is returned. `errno' is available to the caller to use.
     
       PWait: cover function for wait.
     
       PID is the process id of the task to wait for. Status is the
       `status' argument to wait. Flags is currently unused (allows
       future enhancement without breaking upward compatibility). Pass 0
       for now.
     
       The result is the process ID of the child reaped, or -1 for
       failure.
     
       On systems that don't support waiting for a particular child, PID
       is ignored. On systems like MSDOS that don't really multitask
       PWait is just a mechanism to provide a consistent interface for
       the caller. }
     function  PExecute (ProgramName: CString; Arguments: PCStrings; var
       ErrMsg: String; Flags: Integer): Integer; asmname '_p_pexecute';
     function  PWait (PID: Integer; var Status: Integer; Flags: Integer):
       Integer; asmname '_p_pwait';


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
IA32, 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 IA32, 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 IA32 platform. This
       unit is *not* portable. It works only on IA32 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-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-}
     {$ifndef __i386__}
     {$error The Ports unit is only for the IA32 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-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__ < 20000412}
     {$error This unit requires GPC release 20000412 or newer.}
     {$endif}
     
     unit Printer;
     
     interface
     
     uses GPC {$ifndef __OS_DOS__}, Pipe {$endif};
     
     var
       { Dos-like systems: writing to a printer device }
     
       { The file name to write printer output into }
       PrinterDeviceName: PString = @'prn';
     
       { Unix-like systems: printing via a printer program }
     
       { 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: PString = @'lpr';
     
       { Optional command line parameters for the printer program.
         Ignored when nil. }
       PrinterArguments: PPStrings = 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;
     
     { 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 `http://www.gnu-pascal.de/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 http://www.gnu-pascal.de/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)
       `AB'            `AB'            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-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.
     
       Please also note the license of the rx library. }
     
     {$gnu-pascal,I-}
     {$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 matching. 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 matching 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 whether MatchPosition is 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';


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

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

   The following listing contains the interface of the Strings unit.

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

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

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

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

     { BP compatible Strings unit
     
       Copyright (C) 1999-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 Strings;
     
     interface
     
     uses GPC;
     
     function  StrLen     (Src: CString): SizeType; asmname '_p_strlen';
     function  StrEnd     (Src: CString): CString; asmname '_p_strend';
     function  StrMove    (Dest, Source: CString; Count: SizeType):
       CString; asmname '_p_strmove';
     function  StrCopy    (Dest, Source: CString): CString;
       asmname '_p_strcpy';
     function  StrECopy   (Dest, Source: CString): CString;
       asmname '_p_strecpy';
     function  StrLCopy   (Dest, Source: CString; MaxLen: SizeType):
       CString; asmname '_p_strlcpy';
     function  StrPCopy   (Dest: CString; const Source: String): CString;
       asmname '_p_cstringcopystring';
     function  StrCat     (Dest, Source: CString): CString;
       asmname '_p_strcat';
     function  StrLCat    (Dest, Source: CString; MaxLen: SizeType):
       CString; asmname '_p_strlcat';
     function  StrComp    (s1, s2: CString): Integer;
       asmname '_p_strcmp';
     function  StrIComp   (s1, s2: CString): Integer;
       asmname '_p_strcasecmp';
     function  StrLComp   (s1, s2: CString; MaxLen: SizeType): Integer;
       asmname '_p_strlcmp';
     function  StrLIComp  (s1, s2: CString; MaxLen: SizeType): Integer;
       asmname '_p_strlcasecmp';
     function  StrScan    (Src: CString; Ch: Char): CString;
       asmname '_p_strscan';
     function  StrRScan   (Src: CString; Ch: Char): CString;
       asmname '_p_strrscan';
     function  StrPos     (aString, SubString: CString): CString;
       asmname '_p_strpos';
     function  StrRPos    (aString, SubString: CString): CString;
       asmname '_p_strrpos';
     function  StrUpper   (s: CString): CString; asmname '_p_strupper';
     function  StrLower   (s: CString): CString; asmname '_p_strlower';
     function  StrPas     (aString: CString): TString;
       asmname '_p_strpas';
     function  StrEmpty   (s: CString): Boolean; asmname '_p_strempty';
     function  StrNew     (Src: CString): CString; asmname '_p_strdup';
     procedure StrDispose (s: CString); asmname '_p_dispose';

