+ Converted to XML

docs/crt.tex

@@ -1,487 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1997, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA. 
-%
-\chapter{The CRT unit.}
-\label{ch:crtunit}
-
-\FPCexampledir{crtex}
-This chapter describes the \var{CRT} unit for Free Pascal, both under \dos
-\linux and \windows. The unit was first written for \dos by Florian kl\"ampfl. 
-The unit was ported to \linux by Mark May\footnote{Current
-e-mail address \textsf{[email protected]}}, and enhanced by Micha\"el Van Canneyt
-and Peter Vreman. It works on the \linux console, and in xterm and rxvt windows
-under X-Windows. The functionality for both is the same, except that under
-\linux the use of an early implementation (versions 0.9.1 and earlier of the
-compiler) the crt unit automatically cleared the screen at program startup.
-
-There are some caveats when using the CRT unit:
-\begin{itemize}
-\item Programs using the CRT unit will {\em not} be usable when input/output 
-is being redirected on the command-line.
-
-\item For similar reasons they are not usable as CGI-scripts for use with a 
-webserver. 
-
-\item The use of the CRT unit and the graph unit may not always be supported. 
-
-\item On \linux or other unix OSes , executing other programs that expect 
-special terminal behaviour (using one of the special functions in the linux
-unit) will not work. The terminal is set in RAW mode, which will destroy
-most terminal emulation settings.
-\end{itemize}
-
-This chapter is divided in two sections. 
-\begin{itemize}
-\item The first section lists the pre-defined constants, types and variables. 
-\item The second section describes the functions which appear in the
-interface part of the CRT unit.
-\end{itemize}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Types, Variables, Constants
-\section{Types, Variables, Constants}
-Color definitions :
-\begin{verbatim}
-  Black = 0;
-  Blue = 1;
-  Green = 2;
-  Cyan = 3;
-  Red = 4;
-  Magenta = 5;
-  Brown = 6;
-  LightGray = 7;
-  DarkGray = 8;
-  LightBlue = 9;
-  LightGreen = 10;
-  LightCyan = 11;
-  LightRed = 12;
-  LightMagenta = 13;
-  Yellow = 14;
-  White = 15;
-  Blink = 128;
-\end{verbatim}
-Miscellaneous constants
-\begin{verbatim}
-  TextAttr: Byte = $07;
-  TextChar: Char = ' ';
-  CheckBreak: Boolean = True;
-  CheckEOF: Boolean = False;
-  CheckSnow: Boolean = False;
-  DirectVideo: Boolean = False;
-  LastMode: Word = 3;
-  WindMin: Word = $0;
-  WindMax: Word = $184f;
-  ScreenWidth = 80;
-  ScreenHeight = 25;
-\end{verbatim}
-Some variables for compatibility with Turbo Pascal. However, they're not
-used by \fpc.
-\begin{verbatim}
-var
-  checkbreak : boolean;
-  checkeof : boolean;
-  checksnow : boolean;
-\end{verbatim}
-The following constants define screen modes on a \dos system:
-\begin{verbatim}
-Const
-  bw40 = 0;
-  co40 = 1;
-  bw80 = 2;
-  co80 = 3;
-  mono = 7;
-\end{verbatim}
-The \var{TextAttr} variable controls the attributes with which characters
-are written to screen.
-\begin{verbatim}
-var TextAttr : byte;
-\end{verbatim}
-The \var{DirectVideo} variable controls the writing to the screen. If it is
-\var{True}, the the cursor is set via direct port access. If \var{False},
-then the BIOS is used. This is defined under \dos only.
-\begin{verbatim}
-var DirectVideo : Boolean;
-\end{verbatim}
-The \var{Lastmode} variable tells you which mode was last selected for the
-screen. It is defined on \dos only.
-\begin{verbatim}
-var lastmode : Word;
-\end{verbatim}
-
-% Procedures and functions.
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Procedures and Functions}
-
-\begin{procedure}{AssignCrt}
-\Declaration
-Procedure AssignCrt (Var F: Text);
-\Description
-\var{AssignCrt} Assigns a file F to the console. Everything written to 
-the file F goes to the console instead. If the console contains a window, 
-everything is written to the window instead.
-
-\Errors
-None.
-\SeeAlso
-\seep{Window}
-\end{procedure}
-
-\FPCexample{ex1}
- 
-\begin{procedure}{CursorBig}
-\Declaration
-Procedure CursorBig ;
-\Description
-Makes the cursor a big rectangle. 
-Not implemented on \linux.
-\Errors
-None.
-\SeeAlso
-\seep{CursorOn}, \seep{CursorOff}
-\end{procedure}
-
-\begin{procedure}{ClrEol}
-\Declaration
-Procedure ClrEol ;
-\Description
- ClrEol clears the current line, starting from the cursor position, to the
-end of the window. The cursor doesn't move
-\Errors
-None.
-\SeeAlso
-\seep{DelLine}, \seep{InsLine}, \seep{ClrScr}
-\end{procedure}
-
-\FPCexample{ex9}
- 
-\begin{procedure}{ClrScr}
-\Declaration
-Procedure ClrScr ;
-\Description
- ClrScr clears the current window (using the current colors), 
-and sets the cursor in the top left
-corner of the current window.
-\Errors
-None.
-\SeeAlso
- \seep{Window} 
-\end{procedure}
-
-\FPCexample{ex8}
- 
-\begin{procedure}{CursorOff}
-\Declaration
-Procedure CursorOff ;
-\Description
-Switches the cursor off (i.e. the cursor is no
-longer visible). 
-Not implemented on \linux.
-\Errors
-None.
-\SeeAlso
-\seep{CursorOn}, \seep{CursorBig}
-\end{procedure}
-\begin{procedure}{CursorOn}
-\Declaration
-Procedure CursorOn ;
-\Description
-Switches the cursor on. 
-Not implemented on \linux.
-\Errors
-None.
-\SeeAlso
-\seep{CursorBig}, \seep{CursorOff}
-\end{procedure}
-\begin{procedure}{Delay}
-\Declaration
-Procedure Delay (DTime: Word);
-\Description
-Delay waits a specified number of milliseconds. The number of specified
-seconds is an approximation, and may be off a lot, if system load is high.
-\Errors
-None
-\SeeAlso
-\seep{Sound}, \seep{NoSound}
-\end{procedure}
-
-\FPCexample{ex15}
- 
-\begin{procedure}{DelLine}
-\Declaration
-Procedure DelLine ;
-\Description
- DelLine removes the current line. Lines following the current line are 
-scrolled 1 line up, and an empty line is inserted at the bottom of the
-current window. The cursor doesn't move.
-\Errors
-None.
-\SeeAlso
-\seep{ClrEol}, \seep{InsLine}, \seep{ClrScr}
-\end{procedure}
-
-\FPCexample{ex11}
- 
-\begin{procedure}{GotoXY}
-\Declaration
-Procedure GotoXY (X: Byte; Y: Byte);
-\Description
- Positions the cursor at \var{(X,Y)}, \var{X} in horizontal, \var{Y} in
-vertical direction relative to the origin of the current window. The origin
-is located at \var{(1,1)}, the upper-left corner of the window.
-
-\Errors
-None.
-\SeeAlso
- \seef{WhereX}, \seef{WhereY}, \seep{Window} 
-\end{procedure}
-
-\FPCexample{ex6}
- 
-\begin{procedure}{HighVideo}
-\Declaration
-Procedure HighVideo ;
-\Description
- HighVideo switches the output to highlighted text. (It sets the high
-intensity bit of the video attribute)
-
-\Errors
-None.
-\SeeAlso
- \seep{TextColor}, \seep{TextBackground}, \seep{LowVideo},
-\seep{NormVideo}
-\end{procedure}
-
-\FPCexample{ex14}
- 
-\begin{procedure}{InsLine}
-\Declaration
-Procedure InsLine ;
-\Description
- InsLine inserts an empty line at the current cursor position. 
-Lines following the current line are scrolled 1 line down, 
-causing the last line to disappear from the window. 
-The cursor doesn't move.
-\Errors
-None.
-\SeeAlso
-\seep{ClrEol}, \seep{DelLine}, \seep{ClrScr}
-\end{procedure}
-
-\FPCexample{ex10}
- 
-\begin{function}{KeyPressed}
-\Declaration
-Function KeyPressed  : Boolean;
-\Description
- The Keypressed function scans the keyboard buffer and sees if a key has
-been pressed. If this is the case, \var{True} is returned. If not,
-\var{False} is returned. The \var{Shift, Alt, Ctrl} keys are not reported.
-The key is not removed from the buffer, and can hence still be read after
-the KeyPressed function has been called.
-
-\Errors
-None.
-\SeeAlso
-\seef{ReadKey}
-\end{function}
-
-\FPCexample{ex2}
- 
-\begin{procedure}{LowVideo}
-\Declaration
-Procedure LowVideo ;
-\Description
- LowVideo switches the output to non-highlighted text. (It clears the high
-intensity bit of the video attribute)
-
-\Errors
-None.
-\SeeAlso
- \seep{TextColor}, \seep{TextBackground}, \seep{HighVideo},
-\seep{NormVideo}
-\end{procedure}
-For an example, see \seep{HighVideo}
-\begin{procedure}{NormVideo}
-\Declaration
-Procedure NormVideo ;
-\Description
- NormVideo switches the output to the defaults, read at startup. (The
-defaults are read from the cursor position at startup)
-
-\Errors
-None.
-\SeeAlso
- \seep{TextColor}, \seep{TextBackground}, \seep{LowVideo},
-\seep{HighVideo}
-\end{procedure}
-For an example, see \seep{HighVideo}
-\begin{procedure}{NoSound}
-\Declaration
-Procedure NoSound ;
-\Description
-
-Stops the speaker sound.
-This call is not supported on all operating systems.
-\Errors
-None.
-\SeeAlso
-\seep{Sound}
-\end{procedure}
-
-\FPCexample{ex16}
- 
-\begin{function}{ReadKey}
-\Declaration
-Function ReadKey  : Char;
-\Description
-
-The ReadKey function reads 1 key from the keyboard buffer, and returns this.
-If an extended or function key has been pressed, then the zero ASCII code is 
-returned. You can then read the scan code of the key with a second ReadKey
-call.
-\textbf{Remark.} Key mappings under Linux can cause the wrong key to be
-reported by ReadKey, so caution is needed when using ReadKey.  
-
-\Errors
-None.
-\SeeAlso
-\seef{KeyPressed}
-\end{function}
-
-
-\FPCexample{ex3}
-
-
-\begin{procedure}{Sound}
-\Declaration
-Procedure Sound (hz : word);
-\Description
- Sounds the speaker at a frequency of \var{hz}. Under \windows,
- a system sound is played and the frequency parameter is ignored.
- On other operating systems, this routine may not be implemented.
-\Errors
-None.
-\SeeAlso
-\seep{NoSound}
-\end{procedure}
-
-\begin{procedure}{TextBackground}
-\Declaration
-Procedure TextBackground (CL: Byte);
-\Description
-
-TextBackground sets the background color to \var{CL}. \var{CL} can be one of the
-predefined color constants.
-
-\Errors
-None.
-\SeeAlso
- \seep{TextColor}, \seep{HighVideo}, \seep{LowVideo},
-\seep{NormVideo}
-\end{procedure}
-
-\FPCexample{ex13}
- 
-\begin{procedure}{TextColor}
-\Declaration
-Procedure TextColor (CL: Byte);
-\Description
-
-TextColor sets the foreground color to \var{CL}. \var{CL} can be one of the
-predefined color constants.
-
-\Errors
-None.
-\SeeAlso
- \seep{TextBackground}, \seep{HighVideo}, \seep{LowVideo},
-\seep{NormVideo}
-\end{procedure}
-
-\FPCexample{ex12}
-
-\begin{procedure}{TextMode}
-\Declaration
-procedure TextMode(Mode: Integer);
-\Description
-\var{TextMode} sets the textmode of the screen (i.e. the number of lines
-and columns of the screen). The lower byte is use to set the VGA text mode.
-
-This procedure is only implemented on \dos.
-\Errors
-None.
-\SeeAlso
-\seep{Window}
-\end{procedure}
- 
-\begin{function}{WhereX}
-\Declaration
-Function WhereX  : Byte;
-\Description
-
-WhereX returns the current X-coordinate of the cursor, relative to the
-current window. The origin is \var{(1,1)}, in the upper-left corner of the
-window.
-
-\Errors
-None.
-\SeeAlso
- \seep{GotoXY}, \seef{WhereY}, \seep{Window} 
-\end{function}
-
-\FPCexample{ex7}
- 
-\begin{function}{WhereY}
-\Declaration
-Function WhereY  : Byte;
-\Description
-
-WhereY returns the current Y-coordinate of the cursor, relative to the
-current window. The origin is \var{(1,1)}, in the upper-left corner of the
-window.
-
-\Errors
-None.
-\SeeAlso
- \seep{GotoXY}, \seef{WhereX}, \seep{Window} 
-\end{function}
-
-\FPCexample{ex7}
- 
-\begin{procedure}{Window}
-\Declaration
-Procedure Window (X1, Y1, X2, Y2: Byte);
-\Description
- Window creates a window on the screen, to which output will be sent.
-\var{(X1,Y1)} are the coordinates of the upper left corner of the window,
-\var{(X2,Y2)} are the coordinates of the bottom right corner of the window.
-These coordinates are relative to the entire screen, with the top left
-corner equal to \var{(1,1)}
-Further coordinate operations, except for the next Window call,
-are relative to the window's top left corner.
-
-\Errors
-None.
-\SeeAlso
-\seep{GotoXY}, \seef{WhereX}, \seef{WhereY}, \seep{ClrScr}
-\end{procedure}
-
-
-\FPCexample{ex5}
-

docs/dos.tex

@@ -1,1014 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1997, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA. 
-%
-\chapter{The DOS unit.}
-\FPCexampledir{dosex}
-
-This chapter describes the \var{DOS} unit for Free pascal. The \var{DOS}
-unit gives access to some operating system calls related to files, the
-file system, date and time. Except for the \palmos target, this unit is
-available to all supported platforms.
-
-The unit was first written for \dos by Florian Kl\"ampfl. It was ported to 
-\linux by Mark May\footnote{Current e-mail address \textsf{[email protected]}}, 
-and enhanced by Micha\"el Van Canneyt. The \amiga version was ported by
-Nils Sjoholm.
-
-Under non-\dos systems, some of the functionality is lost, as it is either impossible 
-or meaningless to implement it. Other than that, the functionality for all 
-operating systems is the same.
-
-This chapter is divided in three sections:
-\begin{itemize}
-\item The first section lists the pre-defined constants, types and variables. 
-\item The second section gives an overview of all functions available,
-grouped by category.
-\item The third section describes the functions which appear in the
-interface part of the DOS unit.
-\end{itemize}
-
-\section{Types, Variables, Constants}
-
-
-\subsection {Constants}
-The DOS unit implements the following constants:
-
-\subsubsection{File attributes}
-
-The File Attribute constants are used in \seep{FindFirst}, \seep{FindNext} to
-determine what type of special file to search for in addition to normal files. 
-These flags are also used in the \seep{SetFAttr} and \seep{GetFAttr} routines to 
-set and retrieve attributes of files. For their definitions consult 
-\seet{fileattributes}.
-
-\begin{FPCltable}{lll}{Possible file attributes}{fileattributes}
-\hline
-Constant & Description & Value\\ \hline
-\var{readonly} & Read only file & \$01\\
-\var{hidden} & Hidden file & \$02 \\
-\var{sysfile} & System file & \$04\\
-\var{volumeid} & Volume label & \$08\\
-\var{directory} & Directory & \$10\\
-\var{archive} & Archive & \$20\\ 
-\var{anyfile} & Any of the above special files & \$3F\\
-\hline
-\end{FPCltable}
-
-\subsubsection{fmXXXX}
-
-These constants are used in the \var{Mode} field of the \var{TextRec}
-record. Gives information on the filemode of the text I/O. For their
-definitions consult \seet{fmxxxconstants}.
-
-\begin{FPCltable}{lll}{Possible mode constants}{fmxxxconstants}
-\hline
-Constant & Description & Value\\ \hline
-\var{fmclosed} & File is closed & \$D7B0\\
-\var{fminput} & File is read only & \$D7B1 \\
-\var{fmoutput} & File is write only & \$D7B2\\
-\var{fminout} & File is read and write & \$D7B3\\
-\hline
-\end{FPCltable}
-
-\subsubsection{Other}
-
-The following constants are not portable, and should not be used. They
-are present for compatibility only.
-
-\begin{verbatim}
-  {Bitmasks for CPU Flags}
-  fcarry =     $0001;
-  fparity =    $0004;
-  fauxiliary = $0010;
-  fzero =      $0040;
-  fsign =      $0080;
-  foverflow  = $0800;
-\end{verbatim}  
-  
-\subsection{Types}
-The following string types are defined for easy handling of
-filenames :
-\begin{verbatim}
-  ComStr  = String[255];   { For command-lines } 
-  PathStr = String[255];   { For full path for file names }
-  DirStr  = String[255];   { For Directory and (DOS) drive string }
-  NameStr = String[255];   { For Name of file }
-  ExtStr  = String[255];   { For Extension of file }
-\end{verbatim}
-\begin{verbatim}
-  SearchRec = Packed Record
-    Fill : array[1..21] of byte;  
-    { Fill replaced with declarations below, for Linux}
-    Attr : Byte; {attribute of found file}
-    Time : LongInt; {last modify date of found file}
-    Size : LongInt; {file size of found file}
-    Reserved : Word; {future use}
-    Name : String[255]; {name of found file}
-    SearchSpec: String[255]; {search pattern}
-    NamePos: Word; {end of path, start of name position}
-    End;
-\end{verbatim}
-Under \linux, the \var{Fill} array is replaced with the following:
-\begin{verbatim}
-    SearchNum: LongInt; {to track which search this is}
-    SearchPos: LongInt; {directory position}
-    DirPtr: LongInt; {directory pointer for reading directory}
-    SearchType: Byte;  {0=normal, 1=open will close}
-    SearchAttr: Byte; {attribute we are searching for}
-    Fill: Array[1..07] of Byte; {future use}
-\end{verbatim}
-This is because the searching meachanism on Unix systems is substantially
-different from \dos's, and the calls have to be mimicked.
-\begin{verbatim}
-const
-  filerecnamelength = 255;
-type
-  FileRec = Packed Record
-    Handle,
-    Mode,  
-    RecSize   : longint;
-    _private  : array[1..32] of byte;
-    UserData  : array[1..16] of byte;
-    name      : array[0..filerecnamelength] of char;
-  End;
-\end{verbatim}
-\var{FileRec} is used for internal representation of typed and untyped files.
-Text files are handled by the following types :
-\begin{verbatim}
-const
-  TextRecNameLength = 256;
-  TextRecBufSize    = 256;
-type
-  TextBuf = array[0..TextRecBufSize-1] of char;
-  TextRec = Packed Record
-    Handle,
-    Mode,  
-    bufsize,
-    _private,
-    bufpos,  
-    bufend    : longint;
-    bufptr    : ^textbuf;
-    openfunc,
-    inoutfunc,
-    flushfunc,
-    closefunc : pointer;
-    UserData  : array[1..16] of byte;
-    name      : array[0..textrecnamelength-1] of char;
-    buffer    : textbuf;
-  End;
-\end{verbatim}
-Remark that this is not binary compatible with the Turbo Pascal definition
-of \var{TextRec}, since the sizes of the different fields are different.
-\begin{verbatim}
-    Registers = record
-      case i : integer of
-        0 : (ax,f1,bx,f2,cx,f3,dx,f4,bp,f5,si,
-             f51,di,f6,ds,f7,es,f8,flags,fs,gs : word);
-        1 : (al,ah,f9,f10,bl,bh,f11,f12,
-             cl,ch,f13,f14,dl,dh : byte);
-        2 : (eax,  ebx,  ecx,  edx,  ebp,  esi,  edi : longint);
-        End;
-\end{verbatim}
-The  \var{registers} type is used in the \var{MSDos} call.
-\begin{verbatim}
-  DateTime = record
-    Year: Word;
-    Month: Word;
-    Day: Word;
-    Hour: Word;
-    Min: Word;
-    Sec: word;
-    End;
-\end{verbatim}
-The \var{DateTime} type is used in \seep{PackTime} and \seep{UnPackTime} for
-setting/reading file times with \seep{GetFTime} and \seep{SetFTime}.
-\subsection{Variables}
-\begin{verbatim}
-    DosError : integer;
-\end{verbatim}
-The \var{DosError} variable is used by the procedures in the \dos unit to 
-report errors. It can have the following values :
-\begin{center}
-\begin{tabular}{cl}
-2 & File not found. \\
-3 & path not found. \\
-5 & Access denied. \\
-6 & Invalid handle. \\
-8 & Not enough memory. \\
-10 & Invalid environment. \\
-11 & Invalid format. \\
-18 & No more files.
-\end{tabular}
-\end{center}
-Other values are possible, but are not documented.
-%\begin{verbatim}
-%    drivestr : array [0..26] of pchar;
-%\end{verbatim}
-%This variable is defined in the \linux version of the \dos unit. It is used
-%in the \seef{DiskFree} and \seef{DiskSize} calls.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Functions and procedures by category
-\section{Function list by category}
-What follows is a listing of the available functions, grouped by category.
-For each function there is a reference to the page where you can find the
-function.
-
-\subsection{File handling}
-Routines to handle files on disk.
-\begin{funclist}
-\funcrefl{FExpand}{Dos:FExpand}{Expand filename to full path}
-\procref{FindClose}{Close finfirst/findnext session}
-\procref{FindFirst}{Start find of file}
-\procref{FindNext}{Find next file}
-\funcrefl{FSearch}{Dos:FSearch}{Search for file in a path}
-\procref{FSplit}{Split filename in parts}
-\procref{GetFAttr}{Return file attributes}
-\procref{GetFTime}{Return file time}
-\funcref{GetLongName}{Convert short filename to long filename (DOS only)}
-\funcref{GetShortName}{Convert long filename to short filename (DOS only)}
-\procref{SetFAttr}{Set file attributes}
-\procref{SetFTime}{Set file time}
-\end{funclist}
-
-\subsection{Directory and disk handling}
-Routines to handle disk information.
-\begin{funclist}
-\procref{AddDisk}{Add disk to list of disks (UNIX only)}
-\funcref{DiskFree}{Return size of free disk space}
-\funcref{DiskSize}{Return total disk size}
-\end{funclist}
-
-\subsection{Process handling}
-Functions to handle process information and starting new processes.
-\begin{funclist}
-\funcref{DosExitCode}{Exit code of last executed program}
-\funcref{EnvCount}{Return number of environment variables}
-\funcref{EnvStr}{Return environment string pair}
-\procref{Exec}{Execute program}
-\funcrefl{GetEnv}{Dos:GetEnv}{Return specified environment string}
-\end{funclist}
-
-\subsection{System information}
-Functions for retrieving and setting general system information such as date
-and time.
-\begin{funclist}
-\funcref{DosVersion}{Get OS version}
-\procref{GetCBreak}{Get setting of control-break handling flag}
-\procrefl{GetDate}{Dos:GetDate}{Get system date}
-\procref{GetIntVec}{Get interrupt vector status}
-\procrefl{GetTime}{Dos:GetTime}{Get system time}
-\procref{GetVerify}{Get verify flag}
-\procref{Intr}{Execute an interrupt}
-\procref{Keep}{Keep process in memory and exit}
-\procref{MSDos}{Execute MS-dos function call}
-\procref{PackTime}{Pack time for file time}
-\procref{SetCBreak}{Set control-break handling flag}
-\procref{SetDate}{Set system date}
-\procref{SetIntVec}{Set interrupt vectors}
-\procref{SetTime}{Set system time}
-\procref{SetVerify}{Set verify flag}
-\procref{SwapVectors}{Swap interrupt vectors}
-\procref{UnPackTime}{Unpack file time}
-\end{funclist}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Functions and procedures
-\section{Functions and Procedures}
-\begin{procedure}{AddDisk}
-\Declaration
-Procedure AddDisk (Const S : String);
-\Description
-\var{AddDisk} adds a filename \var{S} to the internal list of disks. It is
-implemented for systems which do not use DOS type drive letters.
- This list is used to determine which disks to use in the \seef{DiskFree}
-and \seef{DiskSize} calls. 
-The \seef{DiskFree} and \seef{DiskSize} functions need a file on the 
-specified drive, since this is required for the \var{statfs} system call.
-The names are added sequentially. The dos
-initialization code presets the first three disks to:
-\begin{itemize}
-\item \var{'.'} for the current drive, 
-\item \var{'/fd0/.'} for the first floppy-drive (linux only).
-\item \var{'/fd1/.'} for the second floppy-drive (linux only).
-\item \var{'/'} for the first hard disk.
-\end{itemize}
-The first call to \var{AddDisk} will therefore add a name for the second
-harddisk, The second call for the third drive, and so on until 23 drives
-have been added (corresponding to drives \var{'D:'} to \var{'Z:'})
-\Errors
-None
-\SeeAlso
-\seef{DiskFree}, \seef{DiskSize} 
-\end{procedure}
-
-
-\begin{function}{DiskFree}
-\Declaration
-Function DiskFree (Drive: byte) : int64;
-\Description
-
-\var{DiskFree} returns the number of free bytes on a disk. The parameter
-\var{Drive} indicates which disk should be checked. This parameter is 1 for
-floppy \var{a:}, 2 for floppy \var{b:}, etc. A value of 0 returns the free
-space on the current drive. 
-
-\textbf{For \unix only:}\\
-The \var{diskfree} and \var{disksize} functions need a file on the 
-specified drive, since this is required for the \var{statfs} system call.
-These filenames are set in the initialization of the dos unit, and have 
-been preset to :
-\begin{itemize}
-\item \var{'.'} for the current drive, 
-\item \var{'/fd0/.'} for the first floppy-drive (linux only).
-\item \var{'/fd1/.'} for the second floppy-drive (linux only).
-\item \var{'/'} for the first hard disk.
-\end{itemize}
-There is room for 1-26 drives. You can add a drive with the
-\seep{AddDisk} procedure.
-These settings can be coded in \var{dos.pp}, in the initialization part.
-
-\Errors
--1 when a failure occurs, or an invalid drive number is given.
-\SeeAlso
-\seef{DiskSize}, \seep{AddDisk}
-\end{function}
-
-\FPCexample{ex6}
-
-\begin{function}{DiskSize}
-\Declaration
-Function DiskSize (Drive: byte) : int64;
-\Description
-
-\var{DiskSize} returns the total size (in bytes) of a disk. The parameter
-\var{Drive} indicates which disk should be checked. This parameter is 1 for
-floppy \var{a:}, 2 for floppy \var{b:}, etc. A value of 0 returns the size
-of the current drive. 
-
-\textbf{For \unix only:}\\
-The \var{diskfree} and \var{disksize} functions need a file on the specified drive, since this
-is required for the \var{statfs} system call.
-  These filenames are set in the initialization of the dos unit, and have 
-been preset to :
-\begin{itemize}
-\item \var{'.'} for the current drive, 
-\item \var{'/fd0/.'} for the first floppy-drive (linux only).
-\item \var{'/fd1/.'} for the second floppy-drive (linux only).
-\item \var{'/'} for the first hard disk.
-\end{itemize}
-There is room for 1-26 drives. You can add a drive with the
-\seep{AddDisk} procedure.
-These settings can be coded in \var{dos.pp}, in the initialization part.
-
-\Errors
--1 when a failure occurs, or an invalid drive number is given.
-\SeeAlso
-\seef{DiskFree}, \seep{AddDisk}
-\end{function}
-For an example, see \seef{DiskFree}.
-\begin{function}{DosExitCode}
-\Declaration
-Function DosExitCode  : Word;
-\Description
-
-\var{DosExitCode} contains (in the low byte) the exit-code of a program 
-executed with the \var{Exec} call.
-\Errors
-None.
-\SeeAlso
-\seep{Exec}
-\end{function}
-
-\FPCexample{ex5}
-
-\begin{function}{DosVersion}
-\Declaration
-Function DosVersion  : Word;
-\Description
-\var{DosVersion} returns the operating system or kernel version. The
-low byte contains the major version number, while the high byte 
-contains the minor version number.
-\Portability
-On systems where versions consists of more then two numbers, 
-only the first two numbers will be returned. For example Linux version 2.1.76 
-will give you DosVersion 2.1. Some operating systems, such as \freebsd, do not
-have system calls to return the kernel version, in that case a value of 0 will
-be returned.
-\Errors
-None.
-\SeeAlso
-
-\end{function}
-
-
-\FPCexample{ex1}
-
-
-\begin{function}{EnvCount}
-\Declaration
-Function EnvCount  : longint;\Description
-\var{EnvCount} returns the number of environment variables.
-\Errors
-None.
-\SeeAlso
-\seef{EnvStr}, \seef{Dos:GetEnv}
-\end{function}
-
-\begin{function}{EnvStr}
-\Declaration
-Function EnvStr (Index: longint) : string;\Description
-
-\var{EnvStr} returns the \var{Index}-th \var{Name=Value} pair from the list
-of environment variables. 
-The index of the first pair is zero.
-\Errors
-The length is limited to 255 characters. 
-\SeeAlso
-\seef{EnvCount}, \seef{Dos:GetEnv}
-\end{function}
-
-\FPCexample{ex13}
-
-\begin{procedure}{Exec}
-\Declaration
-Procedure Exec (const Path: pathstr; const ComLine: comstr);
-\Description
-
-\var{Exec} executes the program in \var{Path}, with the options given by
-\var{ComLine}.
-After the program has terminated, the procedure returns. The Exit value of
-the program can be consulted with the \var{DosExitCode} function.
-
-\Errors
-Errors are reported in \var{DosError}.
-\SeeAlso
-\seef{DosExitCode}
-\end{procedure}
-For an example, see \seef{DosExitCode}
-\begin{functionl}{FExpand}{Dos:FExpand}
-\Declaration
-Function FExpand (const path: pathstr) : pathstr;
-\Description
-
-\var{FExpand} takes its argument and expands it to a complete filename, i.e.
-a filename starting from the root directory of the current drive, prepended
-with the drive-letter or volume name (when supported).
-\Portability
-On case sensitive file systems (such as \unix and \linux), the resulting
-name is left as it is, otherwise it is converted to uppercase.
-\Errors
-\seep{FSplit}
-\SeeAlso
-\end{functionl}
-
-\FPCexample{ex5}
-
-\begin{procedure}{FindClose}
-\Declaration
-Procedure FindClose (Var F: SearchRec);
-\Description
-\var{FindClose} frees any resources associated with the search record
-\var{F}.
-
-This call is needed to free any internal resources allocated by the 
-\seef{FindFirst} or \seef{FindNext} calls.
-
-
-The \linux implementation of the \dos unit therefore keeps a table of open
-directories, and when the table is full, closes one of the directories, and
-reopens another. This system is adequate but slow if you use a lot of
-\var{searchrecs}.
-So, to speed up the findfirst/findnext system, the \var{FindClose} call was
-implemented. When you don't need a \var{searchrec} any more, you can tell
-this to the \dos unit by issuing a \var{FindClose} call. The directory
-which is kept open for this \var{searchrec} is then closed, and the table slot
-freed.
-
-\Portability
-It is recommended to use the \linux call \var{Glob} when looking for files 
-on \linux.
-
-\Errors
-Errors are reported in DosError.
-\SeeAlso
-\seef{Glob}.
-\end{procedure}
-
-\begin{procedure}{FindFirst}
-\Declaration
-Procedure FindFirst (const Path: pathstr; Attr: word; var F: SearchRec);
-\Description
-
-\var{FindFirst} searches the file specified in \var{Path}. Normal files,
-as well as all special files which have the attributes specified in
-\var{Attr} will be returned.
-
-It returns a \var{SearchRec} record for further searching in \var{F}.
-\var{Path} can contain the wildcard characters \var{?} (matches any single
-character) and \var{*} (matches 0 ore more arbitrary characters). In this
-case \var{FindFirst} will return the first file which matches the specified
-criteria.
-If \var{DosError} is different from zero, no file(s) matching the criteria 
-was(were) found.
-
-\Portability
-On \ostwo, you cannot issue two different \var{FindFirst} calls. That is,
-you must close any previous search operation with \seep{FindClose} before
-starting a new one. Failure to do so will end in a Run-Time Error 6 
-(Invalid file handle)
-
-\Errors
-Errors are reported in DosError.
-\SeeAlso
-\seep{FindNext},
-\seep{FindClose}
-\end{procedure}
-
-\FPCexample{ex7}
-
-\begin{procedure}{FindNext}
-\Declaration
-Procedure FindNext (var f: searchRec);
-\Description
-
-\var{FindNext} takes as an argument a \var{SearchRec} from a previous
-\var{FindNext} call, or a \var{FindFirst} call, and tries to find another
-file which matches the criteria, specified in the \var{FindFirst} call.
-If \var{DosError} is different from zero, no more files matching the
-criteria were found.
-\Errors
-\var{DosError} is used to report errors.
-\SeeAlso
-\seep{FindFirst}, \seep{FindClose}
-\end{procedure}
-For an example, see \seep{FindFirst}.
-\begin{functionl}{FSearch}{Dos:FSearch}
-\Declaration
-Function FSearch (Path: pathstr; DirList: string) : pathstr;
-\Description
-\var{FSearch} searches the file \var{Path} in all directories listed in
-\var{DirList}. The full name of the found file is returned.
-\var{DirList} must be a list of directories, separated by semi-colons.
-When no file is found, an empty string is returned.
-\Portability
-On \unix systems, \var{DirList} can also be separated by colons, as is
-customary on those environments.
-\Errors
-None.
-\SeeAlso
-\seefl{FExpand}{Dos:FExpand}
-\end{functionl}
-
-\FPCexample{ex10}
-
- 
-\begin{procedure}{FSplit}
-\Declaration
-Procedure FSplit (path: pathstr; \\ var dir: dirstr; var name: namestr;
-  var ext: extstr);
-\Description
-
-\var{FSplit} splits a full file name into 3 parts : A \var{Path}, a
-\var{Name} and an extension  (in \var{ext}.) 
-The extension is taken to be all letters after the {\em last} dot (.). For 
-\dos, however, an exception is made when \var{LFNSupport=False}, then
-the extension is defined as all characters after the {\em first} dot.
-
-\Errors
-None.
-\SeeAlso
-\seefl{FSearch}{Dos:FSearch}
-\end{procedure}
-
-\FPCexample{ex12}
-
-\begin{procedure}{GetCBreak}
-\Declaration
-Procedure GetCBreak (var breakvalue: boolean);
-\Description
-
-\var{GetCBreak} gets the status of CTRL-Break checking under \dos and \amiga.
-When \var{BreakValue} is \var{false}, then \dos only checks for the 
-CTRL-Break key-press when I/O is performed. When it is set to \var{True},
-then a check is done at every system call.
-\Portability
-Under non-\dos and non-\amiga operating systems, \var{BreakValue} always returns 
-\var{True}.
-\Errors 
-None
-\SeeAlso
-\seep{SetCBreak}
-\end{procedure}
-
-\begin{procedurel}{GetDate}{Dos:GetDate}
-\Declaration
-Procedure GetDate (var year, month, mday, wday: word);\Description
-
-\var{GetDate} returns the system's date. \var{Year} is a number in the range
-1980..2099.\var{mday} is the day of the month,
-\var{wday} is the day of the week, starting with Sunday as day 0.
-\Errors
-None.
-\SeeAlso
-\seepl{GetTime}{Dos:GetTime},\seep{SetDate}
-\end{procedurel}
-
-\FPCexample{ex2}
-
-\begin{functionl}{GetEnv}{Dos:GetEnv}
-\Declaration
-Function GetEnv (EnvVar: String) : String;
-\Description
-
-\var{Getenv} returns the value of the environment variable \var{EnvVar}.
-When there is no environment variable \var{EnvVar} defined, an empty
-string is returned.
-\Portability
-Under some operating systems (such as \unix), case is important when looking
-for \var{EnvVar}.
-\Errors
-None.
-\SeeAlso
-\seef{EnvCount}, \seef{EnvStr}
-\end{functionl}
-
-\FPCexample{ex14}
-
-\begin{procedure}{GetFAttr}
-\Declaration
-Procedure GetFAttr (var F; var Attr: word);
-\Description
-
-\var{GetFAttr} returns the file attributes of the file-variable \var{f}.
- \var{F} can be a untyped or typed file, or of type \var{Text}. \var{f} must
-have been assigned, but not opened. The attributes can be examined with the
-following constants :
-\begin{itemize}
-\item \var{ReadOnly}
-\item \var{Hidden}
-\item \var{SysFile}
-\item \var{VolumeId}
-\item \var{Directory}
-\item \var{Archive}
-\end{itemize}
-Under \linux, supported attributes are:
-\begin{itemize}
-\item \var{Directory}
-\item \var{ReadOnly} if the current process doesn't have access to the file.
-\item \var{Hidden} for files whose name starts with a dot \var{('.')}.
-\end{itemize}
-
-\Errors
-Errors are reported in \var{DosError}
-\SeeAlso
-\seep{SetFAttr}
-\end{procedure}
-
-\FPCexample{ex8}
-
-\begin{procedure}{GetFTime}
-\Declaration
-Procedure GetFTime (var F; var Time: longint);
-\Description
-
-\var{GetFTime} returns the modification time of a file.
-This time is encoded and must be decoded with \var{UnPackTime}. 
-\var{F} must be a file type, which has been assigned, and
-opened.
-\Errors
-Errors are reported in \var{DosError}
-\SeeAlso
-\seep{SetFTime}, \seep{PackTime},\seep{UnPackTime}
-\end{procedure}
-
-\FPCexample{ex9}
-
-\begin{procedure}{GetIntVec}
-\Declaration
-Procedure GetIntVec (IntNo: byte; var Vector: pointer);
-\Description
-
-\var{GetIntVec} returns the address of interrupt vector
-\var{IntNo}.
-\Portability
-This call does nothing, it is present for compatibility only.
-\Errors
-None.
-\SeeAlso
-\seep{SetIntVec}
-\end{procedure}
-
-\begin{function}{GetLongName}
-\Declaration
-function GetLongName(var p : String) : boolean;\Description
-This function is only implemented in the GO32V2 version of \fpc.
-
-\var{GetLongName} changes the filename \var{p} to a long filename
-if the \dos call to do this is successful. The resulting string
-is the long  file name corresponding to the short filename \var{p}.
-
-The function returns \var{True} if the \dos call was successful, 
-\var{False} otherwise.
-
-This function should only be necessary when using the DOS extender
-under Windows 95 and higher.
-\Errors
-If the \dos call was not succesfull, \var{False} is returned.
-\SeeAlso
-\seef{GetShortName}
-\end{function}
-
-\begin{function}{GetShortName}
-\Declaration
-function GetShortName(var p : String) : boolean;\Description
-This function is only implemented in the GO32V2 version of \fpc.
-
-\var{GetShortName} changes the filename \var{p} to a short filename
-if the \dos call to do this is successful. The resulting string
-is the short file name corresponding to the long filename \var{p}.
-
-The function returns \var{True} if the \dos call was successful, 
-\var{False} otherwise.
-
-This function should only be necessary when using the DOS extender
-under Windows 95 and higher.
-\Errors
-If the \dos call was not successful, \var{False} is returned.
-\SeeAlso
-\seef{GetLongName}
-\end{function}
-
-\begin{procedurel}{GetTime}{Dos:GetTime}
-\Declaration
-Procedure GetTime (var hour, minute, second, sec100: word);
-\Description
-
-\var{GetTime} returns the system's time. \var{Hour} is a on a 24-hour time
-scale. \var{sec100} is in hundredth of a
-second.
-\Portability
-Certain operating systems (such as \amiga), always set the \var{sec100} field
-to zero.
-\Errors
-None.
-\SeeAlso
-\seepl{GetDate}{Dos:GetDate},
-\seep{SetTime}
-\end{procedurel}
-
-
-\FPCexample{ex3}
-
-
-\begin{procedure}{GetVerify}
-\Declaration
-Procedure GetVerify (var verify: boolean);
-\Description
-
-\var{GetVerify} returns the status of the verify flag under \dos. When
-\var{Verify} is \var{True}, then \dos checks data which are written to disk,
-by reading them after writing. If \var{Verify} is \var{False}, then data
-written to disk are not verified.
-\Portability
-Under non-\dos systems (excluding \ostwo applications running under vanilla DOS),  
-Verify is always \var{True}.
-\Errors
-None.
-\SeeAlso
-\seep{SetVerify}
-\end{procedure}
-\begin{procedure}{Intr}
-\Declaration
-Procedure Intr (IntNo: byte; var Regs: registers);
-\Description
-
-\var{Intr} executes a software interrupt number \var{IntNo} (must be between
-0 and 255), with processor registers set to \var{Regs}. After the interrupt call
-returned, the processor registers are saved in \var{Regs}.
-\Portability
-Under non-\dos operating systems, this call does nothing.
-\Errors
-None.
-\SeeAlso
-\seep{MSDos}, see the \linux unit.
-\end{procedure}
-
-\begin{procedure}{Keep}
-\Declaration
-Procedure Keep (ExitCode: word);
-\Description
-\var{Keep} terminates the program, but stays in memory. This is used for TSR
-(Terminate Stay Resident) programs which catch some interrupt.
-\var{ExitCode} is the same parameter as the \var{Halt} function takes.
-\Portability
-This call does nothing, it is present for compatibility only.
-\Errors
-None.
-\SeeAlso
-\seem{Halt}{}
-\end{procedure}
-\begin{procedure}{MSDos}
-\Declaration
-Procedure MSDos (var regs: registers);
-\Description
-
-\var{MSDos} executes an operating system. This is the same as doing a
-\var{Intr} call with the interrupt number for an os call.
-\Portability
-Under non-\dos operating systems, this call does nothing. On \dos systems,
-this calls interrupt \$21.
-\Errors
-None.
-\SeeAlso
-\seep{Intr}
-\end{procedure}
-\begin{procedure}{PackTime}
-\Declaration
-Procedure PackTime (var T: datetime; var P: longint);
-\Description
-
-\var{UnPackTime} converts the date and time specified in \var{T}
-to a packed-time format which can be fed to \var{SetFTime}.
-\Errors
-None.
-\SeeAlso
-\seep{SetFTime}, \seep{FindFirst}, \seep{FindNext}, \seep{UnPackTime}
-\end{procedure}
-
-\FPCexample{ex4}
-
-\begin{procedure}{SetCBreak}
-\Declaration
-Procedure SetCBreak (breakvalue: boolean);
-\Description
-
-\var{SetCBreak} sets the status of CTRL-Break checking. When 
-\var{BreakValue} is \var{false}, then \dos only checks for the CTRL-Break 
-key-press when I/O is performed. When it is set to \var{True}, then a 
-check is done at every system call.
-\Portability
-Under non-\dos and non-\amiga operating systems, this call does nothing.
-\Errors
-None.
-\SeeAlso
-\seep{GetCBreak}
-\end{procedure}
-\begin{procedure}{SetDate}
-\Declaration
-Procedure SetDate (year,month,day: word);
-\Description
-
-\var{SetDate} sets the system's internal date. \var{Year} is a number
-between 1980 and 2099.
-\Portability
-On a \linux machine, there must be root privileges, otherwise this
-routine will do nothing. On other \unix systems, this call currently
-does nothing.
-\Errors
-None.
-\SeeAlso
-\seep{Dos:GetDate},
-\seep{SetTime}
-\end{procedure}
-
-\begin{procedure}{SetFAttr}
-\Declaration
-Procedure SetFAttr (var F; Attr: word);
-\Description
-
-\var{SetFAttr} sets the file attributes of the file-variable \var{F}.
- \var{F} can be a untyped or typed file, or of type \var{Text}. \var{F} must
-have been assigned, but not opened. The attributes can be a sum of the
-following constants:
-\begin{itemize}
-\item \var{ReadOnly}
-\item \var{Hidden}
-\item \var{SysFile}
-\item \var{VolumeId}
-\item \var{Directory}
-\item \var{Archive}
-\end{itemize}
-
-\Portability
-Under \unix like systems (such as \linux and \beos) the call exists, but is not implemented, 
-i.e. it does nothing.
-\Errors
-Errors are reported in \var{DosError}.
-\SeeAlso
-\seep{GetFAttr}
-\end{procedure}
-\begin{procedure}{SetFTime}
-\Declaration
-Procedure SetFTime (var F; Time: longint);
-\Description
-
-\var{SetFTime} sets the modification time of a file,
-this time is encoded and must be encoded with \var{PackTime}. 
-\var{F} must be a file type, which has been assigned, and
-opened.
-\Portability
-Under \unix like systems (such as \linux and \beos) the call exists, but is not implemented, 
-i.e. it does nothing.
-\Errors
-Errors are reported in \var{DosError}
-\SeeAlso
-\seep{GetFTime}, \seep{PackTime},\seep{UnPackTime}
-\end{procedure}
-
-\begin{procedure}{SetIntVec}
-\Declaration
-Procedure SetIntVec (IntNo: byte; Vector: pointer);
-\Description
-\var{SetIntVec} sets interrupt vector \var{IntNo} to \var{Vector}.
-\var{Vector} should point to an interrupt procedure.
-\Portability
-This call does nothing, it is present for compatibility only.
-\Errors
-None.
-\SeeAlso
-\seep{GetIntVec}
-\end{procedure}
-
-\begin{procedure}{SetTime}
-\Declaration
-Procedure SetTime (hour,minute,second,sec100: word);
-\Description
-\var{SetTime} sets the system's internal clock. The \var{Hour} parameter is
-on a 24-hour time scale.
-\Portability
-On a \linux machine, there must be root privileges, otherwise this
-routine will do nothing. On other \unix systems, this call currently
-does nothing.
-\Errors
-None.
-\SeeAlso
-\seep{Dos:GetTime}, \seep{SetDate}
-\end{procedure}
-\begin{procedure}{SetVerify}
-\Declaration
-Procedure SetVerify (verify: boolean);
-\Description
-
-\var{SetVerify} sets the status of the verify flag under \dos. When
-\var{Verify} is \var{True}, then \dos checks data which are written to disk,
-by reading them after writing. If \var{Verify} is \var{False}, then data
-written to disk are not verified.
-\Portability
-Under non-\dos operating systems (excluding \ostwo applications running
-under vanilla dos), Verify is always \var{True}.
-\Errors
-None.
-\SeeAlso
-\seep{SetVerify}
-\end{procedure}
-\begin{procedure}{SwapVectors}
-\Declaration
-Procedure SwapVectors ;
-\Description
-
-\var{SwapVectors} swaps the contents of the internal table of interrupt 
-vectors with the current contents of the interrupt vectors.
-This is called typically in before and after an \var{Exec} call.
-
-\Portability
-Under certain operating systems, this routine may be implemented
-as an empty stub.
-\Errors
-None.
-\SeeAlso
-\seep{Exec}, \seep{SetIntVec}
-\end{procedure}
-\begin{procedure}{UnPackTime}
-\Declaration
-Procedure UnPackTime (p: longint; var T: datetime);
-\Description
-
-\var{UnPackTime} converts the file-modification time in \var{p}
-to a \var{DateTime} record. The file-modification time can be 
-returned by \var{GetFTime}, \var{FindFirst} or \var{FindNext} calls.
-\Errors
-None.
-\SeeAlso
-\seep{GetFTime}, \seep{FindFirst}, \seep{FindNext}, \seep{PackTime}
-\end{procedure}
-For an example, see \seep{PackTime}.
-
-

docs/dxeload.tex

@@ -1,60 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1997, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA.
-%
-\chapter{The DXELOAD unit}
-\section{Introduction}
-The \file{dxeload} unit was implemented by Pierre M\"uller for \dos,
-it allows to load a DXE file (an object file with 1 entry point)
-into memory and return a pointer to the entry point.
-
-It exists only for \dos.
-
-\section{Constants, types and variables}
-\subsection{Constants}
-The following constant is the magic number, found in the header of a DXE
-file.
-\begin{verbatim}
-DXE_MAGIC  = $31455844;
-\end{verbatim}
-\subsection{Types}
-The following record describes the header of a DXE file. It is used to
-determine the magic number of the DXE file and number of relocations that 
-must be done when the object file i sloaded in memory.
-\begin{verbatim}
-dxe_header = record
-   magic,
-   symbol_offset,
-   element_size,
-   nrelocs       : longint;
-end;
-\end{verbatim}
-
-\section{Functions and Procedures}
-\begin{functionl}{dxe\_load}{dxeload}
-\Declaration
-function dxe\_load(filename : string) : pointer;
-\Description
-\var{dxe\_load} loads the contents of the file \var{filename} into memory.
-It performs the necessary relocations in the object code, and returns then
-a pointer to the entry point of the code.
-\Errors
-If an error occurs during the load or relocations, \var{Nil} is returned.
-\end{functionl}
-For an example, see the \file{emu387} unit in the RTL.

docs/emu387.tex

@@ -1,62 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1997, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA.
-%
-\chapter{The EMU387 unit}
-The \file{emu387} unit was written by Pierre M\"uller for \dos. It
-sets up the coprocessor emulation for FPC under \dos. It is not necessary to
-use this unit on other OS platforms because they either simply do not run on 
-a machine without coprocessor, or they provide the coprocessor emulation 
-themselves.
-
-It shouldn't be necessary to use the function in this unit, it should be
-enough to place this unit in the \var{uses} clause of your program to
-enable the coprocessor emulation under \dos. The unit initialization
-code will try and load the coprocessor emulation code and initialize it.
-
-\section{Functions and procedures}
-\begin{function}{npxsetup}
-\Declaration
-procedure npxsetup(prog\_name : string);
-\Description
-\var{npxsetup} checks whether a coprocessor is found. If not, it loads the 
-file \file{wmemu387.dxe} into memory and initializes the code in it.
-
-If the environment variable \var{387} is set to \var{N}, then the emulation
-will be loaded, even if there is a coprocessor present. If the variable
-doesn't exist, or is set to any other value, the unit will try to detect 
-the presence of a coprocessor unit.
-
-The function searches the file \file{wmemu387.dxe} in the following way:
-\begin{enumerate}
-\item If the environment variable \var{EMU387} is set, then it is assumed
-to point at the \file{wmemu387.dxe} file.
-\item if the environment variable \var{EMU387} does not exist, then the 
-function will take the path part of  \var{prog\_name} and look in that
-directory for the file \file{wmemu387.dxe}.
-\end{enumerate}
-
-It should never be necessary to call this function, because the
-initialization code of the unit contains a call to the function with
-as an argument \var{paramstr(0)}. This means that you should deliver the
-file \var{wmemu387.dxe} together with your program.
-\Errors
-If there is an error, an error message is printed to standard error, and
-the program is halted, since any floating-point code is bound to fail anyhow.
-\end{function}

docs/getopts.tex

@@ -1,143 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1997, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA. 
-%
-\chapter{The GETOPTS unit.}
-\FPCexampledir{optex}
-
-This document describes the GETOPTS unit for Free Pascal. It was written for
-\linux\ by Micha\"el Van Canneyt. It now also works for all supported platforms.
-
-The getopts unit provides a mechanism to handle command-line options in
-a structured way, much like the GNU getopts mechanism. It allows you to
-define the valid options for you program, and the unit will then parse the
-command-line options for you, and inform you of any errors.
-
-The chapter is divided in 2 sections:
-\begin{itemize}
-\item The first section lists types, constants and variables from the
-interface part of the unit.
-\item The second section describes the functions defined in the unit.
-\end{itemize}
-\section {Types, Constants and variables : }
-\subsection{Constants}
-\var{No\_Argument=0} : Specifies that a long option does not take an
-argument. \\
-\var{Required\_Argument=1} : Specifies that a long option needs an
-argument. \\
-\var{Optional\_Argument=2} : Specifies that a long option optionally takes an
-argument. \\
-\var{EndOfOptions=\#255}  : Returned by getopt, getlongopts to indicate that
-there are no more options.
-\subsection{Types}
-\begin{verbatim}
-TOption = record
-  Name    : String;
-  Has_arg : Integer;
-  Flag    : PChar;
-  Value   : Char;
-  end;
-POption = ^TOption;
-\end{verbatim}
-The \var{option} type is used to communicate the long options to \var{GetLongOpts}.
-The \var{Name} field is the name of the option. \var{Has\_arg} specifies if the option
-wants an argument, \var{Flag} is a pointer to a \var{char}, which is set to
-\var{Value}, if it is non-\var{nil}. 
-\var{POption} is a pointer to a
-\var{Option} record. It is used as an argument to the \var{GetLongOpts}
-function.
-\subsection{Variables}
-\var{OptArg:String} \ Is set to the argument of an option, if the option needs
-one.\\
-\var{Optind:Longint} \ Is the index of the current \var{paramstr()}. When
-all options have been processed, \var{optind} is the index of the first
-non-option parameter. This is a read-only variable. Note that it can become
-equal to \var{paramcount+1}\\
-\var{OptErr:Boolean} \ Indicates whether \var{getopt()} prints error
-messages.\\
-\var{OptOpt:Char} \  In case of an error, contains the character causing the 
-error.
-\section {Procedures and functions}
-\begin{function}{GetLongOpts}
-\Declaration
-Function GetLongOpts (Shortopts : String, LongOpts : POption; var Longint
-: Longint ) : Char;
-
-\Description
-
-Returns the next option found on the command-line, taking into account long
-options as well. If no more options are
-found, returns \var{EndOfOptions}. If the option requires an argument, it is
-returned in the \var{OptArg} variable.
-\var{ShortOptions} is a string containing all possible one-letter options.
-(see \seef{Getopt} for its description and use)
-\var{LongOpts} is a pointer to the first element of an array of \var{Option} 
-records, the last of which needs a name of zero length.  
-The function tries to match the names even partially (i.e. \var{--app} 
-will match e.g. the \var{append} option), but will report an error in case of
-ambiguity.
-If the option needs an argument, set \var{Has\_arg} to
-\var{Required\_argument}, if the option optionally has an argument, set
-\var{Has\_arg} to \var{Optional\_argument}. If the option needs no argument,
-set \var{Has\_arg} to zero.
-Required arguments can be specified in two ways : 
-\begin{enumerate}
-\item \ Pasted to the option : \var{--option=value}
-\item \ As a separate argument : \var {--option value}
-\end{enumerate}
-Optional arguments can only be specified through the first method.
-
-\Errors
- see \seef{Getopt}, \seem{getopt}{3}
-\SeeAlso
-Getopt
-\end{function}
-\begin{function}{Getopt}
-\Declaration
-Function Getopt (Shortopts : String) : Char;
-
-\Description
-
-Returns the next option found on the command-line. If no more options are
-found, returns \var{EndOfOptions}. If the option requires an argument, it is
-returned in the \var{OptArg} variable.
-\var{ShortOptions} is a string containing all possible one-letter options.
-If a letter is followed by a colon (:), then that option needs an argument.
-If a letter is followed by 2 colons, the option has an optional argument.
-If the first character of \var{shortoptions} is a \var{'+'} then options following a non-option are
-regarded as non-options (standard Unix behavior). If it is a \var{'-'},
-then all non-options are treated as arguments of a option with character
-\var{\#0}. This is useful for applications that require their options in
-the exact order as they appear on the command-line.
-If the first character of \var{shortoptions} is none of the above, options
-and non-options are permuted, so all non-options are behind all options.
-This allows options and non-options to be in random order on the command
-line.
-
-\Errors
- 
-Errors are reported through giving back a \var{'?'} character. \var{OptOpt}
-then gives the character which caused the error. If \var{OptErr} is
-\var{True} then getopt prints an error-message to \var{stdout}.
-
-\SeeAlso
-\seef{GetLongOpts}, \seem{getopt}{3}
-\end{function}
-
-\FPCexample{optex}

docs/go32.tex

@@ -1,1603 +0,0 @@
-\chapter{The GO32 unit}
-\label{ch:go32unit}
-
-\FPCexampledir{go32ex}
-This chapter of the documentation describe the GO32 unit for the Free Pascal
-compiler under \dos. It was donated by Thomas Schatzl
-(tom\_at\[email protected]), for which my thanks.
-This unit was first written for \dos by Florian Kl"ampfl.
-This chapter is divided in four sections. The first two sections are an
-introduction to the GO32 unit. The third section lists the pre-defined
-constants, types and variables. The last section describes the functions
-which appear in the interface part of the GO32 unit.
-\section{Introduction}
-These docs contain information about the GO32 unit. Only the GO32V2 DPMI
-mode is discussed by me here due to the fact that new applications shouldn't
-be created with the older GO32V1 model. The go32v2 version is much more advanced and
-better. Additionally a lot of functions only work in DPMI mode anyway.
-I hope the following explanations and introductions aren't too confusing at
-all. If you notice an error or bug send it to the FPC mailing list or
-directly to me.
-So let's get started and happy and error free coding I wish you....
-Thomas Schatzl, 25. August 1998
-\section{Protected mode memory organization}
-\subsection{What is DPMI}
-The \dos Protected Mode Interface helps you with various aspects of protected
-mode programming. These are roughly divided into descriptor handling, access
-to \dos memory, management of interrupts and exceptions, calls to real mode
-functions and other stuff. Additionally it automatically provides swapping
-to disk for memory intensive applications.
-A DPMI host (either a Windows \dos box or CWSDPMI.EXE) provides these
-functions for your programs.
-\subsection{Selectors and descriptors}
-Descriptors are a bit like real mode segments; they describe (as the name
-implies) a memory area in protected mode. A descriptor contains information
-about segment length, its base address and the attributes of it (i.e. type,
-access rights, ...).
-These descriptors are stored internally in a so-called descriptor table,
-which is basically an array of such descriptors.
-Selectors are roughly an index into this table.
-Because these 'segments' can be up to 4 GB in size, 32 bits aren't
-sufficient anymore to describe a single memory location like in real mode.
-48 bits are now needed to do this, a 32 bit address and a 16 bit sized
-selector. The GO32 unit provides the tseginfo record to store such a
-pointer.
-But due to the fact that most of the time data is stored and accessed in the
-\%ds selector, FPC assumes that all pointers point to a memory location of
-this selector. So a single pointer is still only 32 bits in size. This value
-represents the offset from the data segment base address to this memory
-location.
-\subsection{FPC specialities}
-The \%ds and \%es selector MUST always contain the same value or some system
-routines may crash when called. The \%fs selector is preloaded with the
-DOSMEMSELECTOR variable at startup, and it MUST be restored after use,
-because again FPC relys on this for some functions. Luckily we asm
-programmers can still use the \%gs selector for our own purposes, but for how
-long ?
-See also:
-% tseginfo, dosmemselector, \dos memory access,
- \seefl{get\_cs}{getcs}, 
- \seefl{get\_ds}{getds},
- \seefl{gett\_ss}{getss}, 
- \seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors},
- \seefl{free\_ldt\_descriptor}{freeldtdescriptor},
- \seefl{segment\_to\_descriptor}{segmenttodescriptor},
- \seefl{get\_next\_selector\_increment\_value}{getnextselectorincrementvalue},
- \seefl{get\_segment\_base\_address}{getsegmentbaseaddress},
- \seefl{set\_segment\_base\_address}{setsegmentbaseaddress},
- \seefl{set\_segment\_limit}{setsegmentlimit},
- \seefl{create\_code\_segment\_alias\_descriptor}{createcodesegmentaliasdescriptor} 
-\subsection{\dos memory access}
-\dos memory is accessed by the predefined \var{dosmemselector} selector; 
-the GO32 unit additionally provides some functions to help you with standard tasks,
-like copying memory from heap to \dos memory and the likes. Because of this
-it is strongly recommened to use them, but you are still free to use the
-provided standard memory accessing functions which use 48 bit pointers. The
-third, but only thought for compatibility purposes, is using the
-\var{mem[]}-arrays. These arrays map the whole 1 Mb \dos space. They shouldn't be
-used within new programs.
-To convert a segment:offset real mode address to a protected mode linear
-address you have to multiply the segment by 16 and add its offset. This
-linear address can be used in combination with the DOSMEMSELECTOR variable.
-See also: 
-\seep{dosmemget},
-\seepl{dosmemput}{dosmemput},
-\seepl{dosmemmove}{dosmemmove},
-\seepl{dosmemfillchar}{dosmemfillchar},
-\seepl{dosmemfillword}{dosmemfillword},
-mem[]-arrays, 
-\seepl{seg\_move}{segmove},
-\seepl{seg\_fillchar}{segfillchar},
-\seepl{seg\_fillword}{segfillword}. 
-\subsection{I/O port access}
-The I/O port access is done via the various \seef{inportb}, \seep{outportb}
-functions
-which are available. Additionally Free Pascal supports the Turbo Pascal
-PORT[]-arrays but it is by no means recommened to use them, because they're
-only for compatibility purposes.
-See also: \seep{outportb}, \seef{inportb}, PORT[]-arrays
-\subsection{Processor access}
-These are some functions to access various segment registers (\%cs, \%ds, \%ss)
-which makes your work a bit easier.
-See also: \seefl{get\_cs}{getcs}, \seefl{get\_ds}{getds}, 
-\seefl{get\_ss}{getss} 
-\subsection{Interrupt redirection}
-Interrupts are program interruption requests, which in one or another way
-get to the processor; there's a distinction between software and hardware
-interrupts. The former are explicitely called by an 'int' instruction and
-are a bit comparable to normal functions. Hardware interrupts come from
-external devices like the keyboard or mouse. Functions that handle hardware
-interrupts are called handlers.
-\subsection{Handling interrupts with DPMI}
-The interrupt functions are real-mode procedures; they normally can't be
-called in protected mode without the risk of an protection fault. So the
-DPMI host creates an interrupt descriptor table for the application.
-Initially all software interrupts (except for int 31h, 2Fh and 21h function
-4Ch) or external hardware interrupts are simply directed to a handler that
-reflects the interrupt in real-mode, i.e. the DPMI host's default handlers
-switch the CPU to real-mode, issue the interrupt and switch back to
-protected mode. The contents of general registers and flags are passed to
-the real mode handler and the modified registers and flags are returned to
-the protected mode handler. Segment registers and stack pointer are not
-passed between modes.
-\subsection{Protected mode interrupts vs. Real mode interrupts}
-As mentioned before, there's a distinction between real mode interrupts and
-protected mode interrupts; the latter are protected mode programs, while the
-former must be real mode programs. To call a protected mode interrupt
-handler, an assembly 'int' call must be issued, while the other is called
-via the realintr() or intr() function. Consequently, a real mode interrupt
-then must either reside in \dos memory (<1MB) or the application must
-allocate a real mode callback address via the get\_rm\_callback() function.
-\subsection{Creating own interrupt handlers}
-Interrupt redirection with FPC pascal is done via the set\_pm\_interrupt() for
-protected mode interrupts or via the set\_rm\_interrupt() for real mode
-interrupts.
-\subsection{Disabling interrupts}
-The GO32 unit provides the two procedures disable() and enable() to disable
-and enable all interrupts.
-\subsection{Hardware interrupts}
-Hardware interrupts are generated by hardware devices when something unusual
-happens; this could be a keypress or a mouse move or any other action. This
-is done to minimize CPU time, else the CPU would have to check all installed
-hardware for data in a big loop (this method is called 'polling') and this
-would take much time.
-A standard IBM-PC has two interrupt controllers, that are responsible for
-these hardware interrupts: both allow up to 8 different interrupt sources
-(IRQs, interrupt requests). The second controller is connected to the first
-through IRQ 2 for compatibility reasons, e.g. if controller 1 gets an IRQ 2,
-he hands the IRQ over to controller 2. Because of this up to 15 different
-hardware interrupt sources can be handled.
-IRQ 0 through IRQ 7 are mapped to interrupts 8h to Fh and the second
-controller (IRQ 8 to 15) is mapped to interrupt 70h to 77h.
-All of the code and data touched by these handlers MUST be locked (via the
-various locking functions) to avoid page faults at interrupt time. Because
-hardware interrupts are called (as in real mode) with interrupts disabled,
-the handler has to enable them before it returns to normal program
-execution. Additionally a hardware interrupt must send an EOI (end of
-interrupt) command to the responsible controller; this is acomplished by
-sending the value 20h to port 20h (for the first controller) or A0h (for the
-second controller).
-The following example shows how to redirect the keyboard interrupt.
-\FPCexample{keyclick}
-\subsection{Software interrupts}
-Ordinarily, a handler installed with
-\seefl{set\_pm\_interrupt}{setpminterrupt} only services software
-interrupts that are executed in protected mode; real mode software
-interrupts can be redirected by \seefl{set\_rm\_interrupt}{setrminterrupt}.
-See also \seefl{set\_rm\_interrupt}{setrminterrupt}, 
-\seefl{get\_rm\_interrupt}{getrminterrupt},
-\seefl{set\_pm\_interrupt}{setpminterrupt},
-\seefl{get\_pm\_interrupt}{getpminterrupt}, 
-\seefl{lock\_data}{lockdata}, 
-\seefl{lock\_code}{lockcode}, 
-\seep{enable}, 
-\seep{disable},
-\seepl{outportb}{outportb} 
-Executing software interrupts
-Simply execute a realintr() call with the desired interrupt number and the
-supplied register data structure.
-But some of these interrupts require you to supply them a pointer to a
-buffer where they can store data to or obtain data from in memory. These
-interrupts are real mode functions and so they only can access the first Mb
-of linear address space, not FPC's data segment.
-For this reason FPC supplies a pre-initialized \dos memory location within
-the GO32 unit. This buffer is internally used for \dos functions too and so
-it's contents may change when calling other procedures. It's size can be
-obtained with \seefl{tb\_size}{tbsize} and it's linear address via 
-\seefl{transfer\_buffer}{transferbuffer}.
-Another way is to allocate a completely new \dos memory area via the
-\seefl{global\_dos\_alloc}{globaldosalloc} function for your use and 
-supply its real mode address.
-See also:
-\seefl{tb\_size}{tbsize},
-\seefl{transfer\_buffer}{transferbuffer}.
-\seefl{global\_dos\_alloc}{globaldosalloc},
-\seefl{global\_dos\_free}{globaldosfree},
-\seef{realintr}
-The following examples illustrate the use of software interrupts.
-\FPCexample{softint}
-\FPCexample{rmpmint}
-\subsection{Real mode callbacks}
-The callback mechanism can be thought of as the converse of calling a real
-mode procedure (i.e. interrupt), which allows your program to pass
-information to a real mode program, or obtain services from it in a manner
-that's transparent to the real mode program.
-In order to make a real mode callback available, you must first get the real
-mode callback address of your procedure and the selector and offset of a
-register data structure. This real mode callback address (this is a
-segment:offset address) can be passed to a real mode program via a software
-interrupt, a \dos memory block or any other convenient mechanism.
-When the real mode program calls the callback (via a far call), the DPMI
-host saves the registers contents in the supplied register data structure,
-switches into protected mode, and enters the callback routine with the
-following settings:
-\begin{itemize}
-\item interrupts disabled
-\item \var{\%CS:\%EIP} = 48 bit pointer specified in the original call to 
-\seefl{get\_rm\_callback}{getrmcallback}
-\item \var{\%DS:\%ESI} = 48 bit pointer to to real mode \var{SS:SP}
-\item \var{\%ES:\%EDI} = 48 bit pointer of real mode register data
-structure. 
-\item \var{\%SS:\%ESP} = locked protected mode stack
-\item  All other registers undefined
-\end{itemize}
-The callback procedure can then extract its parameters from the real mode
-register data structure and/or copy parameters from the real mode stack to
-the protected mode stack. Recall that the segment register fields of the
-real mode register data structure contain segment or paragraph addresses
-that are not valid in protected mode. Far pointers passed in the real mode
-register data structure must be translated to virtual addresses before they
-can be used with a protected mode program.
-The callback procedure exits by executing an IRET with the address of the
-real mode register data structure in \var{\%ES:\%EDI}, passing information back to
-the real mode caller by modifying the contents of the real mode register
-data structure and/or manipulating the contents of the real mode stack. The
-callback procedure is responsible for setting the proper address for
-resumption of real mode execution into the real mode register data
-structure; typically, this is accomplished by extracting the return address
-from the real mode stack and placing it into the \var{\%CS:\%EIP} fields of the real
-mode register data structure. After the IRET, the DPMI host switches the CPU
-back into real mode, loads ALL registers with the contents of the real mode
-register data structure, and finally returns control to the real mode
-program.
-All variables and code touched by the callback procedure MUST be locked to
-prevent page faults.
-See also: \seefl{get\_rm\_callback}{getrmcallback},
-\seefl{free\_rm\_callback}{freermcallback}, 
-\seefl{lock\_code}{lockcode}, 
-\seefl{lock\_data}{lockdata} 
-\section{Types, Variables and Constants}
-\subsection{Constants}
-\subsubsection{Constants returned by get\_run\_mode}
-Tells you under what memory environment (e.g. memory manager) the program
-currently runs.
-\begin{verbatim}
-rm_unknown = 0; { unknown }
-rm_raw     = 1; { raw (without HIMEM) } 
-rm_xms     = 2; { XMS (for example with HIMEM, without EMM386) } 
-rm_vcpi    = 3; { VCPI (for example HIMEM and EMM386) } 
-rm_dpmi    = 4; { DPMI (for example \dos box or 386Max) }
-\end{verbatim}
-Note: GO32V2 {\em always} creates DPMI programs, so you need a suitable DPMI
-host like \file{CWSDPMI.EXE} or a Windows \dos box. So you don't need to check it,
-these constants are only useful in GO32V1 mode.
-\subsubsection{Processor flags constants}
-They are provided for a simple check with the flags identifier in the
-trealregs type. To check a single flag, simply do an AND operation with the
-flag you want to check. It's set if the result is the same as the flag
-value.
-\begin{verbatim}
-const carryflag = $001; 
-parityflag      = $004; 
-auxcarryflag    = $010; 
-zeroflag        = $040; 
-signflag        = $080; 
-trapflag        = $100; 
-interruptflag   = $200;
-directionflag   = $400; 
-overflowflag    = $800;
-\end{verbatim}
-\subsection{Predefined types}
-\begin{verbatim}
-type tmeminfo = record
-            available_memory : Longint; 
-            available_pages : Longint;
-            available_lockable_pages : Longint; 
-            linear_space : Longint;
-            unlocked_pages : Longint; 
-            available_physical_pages : Longint;
-            total_physical_pages : Longint; 
-            free_linear_space : Longint;
-            max_pages_in_paging_file : Longint; 
-            reserved : array[0..2] of Longint;
-   end;
-\end{verbatim}
-Holds information about the memory allocation, etc.
-\begin{FPCtable}{ll}{Record description}
-Record entry & Description \\ \hline
-\var{available\_memory} & Largest available free block in bytes. \\
-\var{available\_pages} & Maximum unlocked page allocation in pages \\
-\var{available\_lockable\_pages} &  Maximum locked page allocation in pages. \\
-\var{linear\_space} &  Linear address space size in pages. \\
-\var{unlocked\_pages} & Total number of unlocked pages. \\
-\var{available\_physical\_pages} &  Total number of free pages.\\
-\var{total\_physical\_pages} &  Total number of physical pages. \\
-\var{free\_linear\_space} & Free linear address space in pages.\\
-\var{max\_pages\_in\_paging\_file} &  Size of paging file/partition in
-pages. \\
-\end{FPCtable}
-NOTE: The value of a field is -1 (0ffffffffh) if the value is unknown, it's
-only guaranteed, that \var{available\_memory} contains a valid value.
-The size of the pages can be determined by the get\_page\_size() function.
-\begin{verbatim}
-type 
-trealregs = record
-  case Integer of 
-    1: { 32-bit } 
-      (EDI, ESI, EBP, Res, EBX, EDX, ECX, EAX: Longint; 
-       Flags, ES, DS, FS, GS, IP, CS, SP, SS: Word); 
-    2: { 16-bit } 
-      (DI, DI2, SI, SI2, BP, BP2, R1, R2: Word;
-       BX, BX2, DX, DX2, CX, CX2, AX, AX2: Word);
-    3: { 8-bit } 
-      (stuff: array[1..4] of Longint;
-       BL, BH, BL2, BH2, DL, DH, DL2, DH2, CL,
-       CH, CL2, CH2, AL, AH, AL2, AH2: Byte);
-    4: { Compat } 
-      (RealEDI, RealESI, RealEBP, RealRES, RealEBX, 
-       RealEDX, RealECX, RealEAX: Longint; 
-       RealFlags, RealES, RealDS, RealFS, RealGS, 
-       RealIP, RealCS, RealSP, RealSS: Word);
-    end;
-    registers = trealregs;
-\end{verbatim}
-These two types contain the data structure to pass register values to a
-interrupt handler or real mode callback.
-\begin{verbatim}
-type tseginfo = record
-             offset : Pointer; segment : Word; end;
-\end{verbatim}
-This record is used to store a full 48-bit pointer. This may be either a
-protected mode selector:offset address or in real mode a segment:offset
-address, depending on application.
-See also: Selectors and descriptors, \dos memory access, Interrupt
-redirection
-\subsection{Variables.}
-\begin{verbatim}
-var dosmemselector : Word;
-\end{verbatim}
-Selector to the \dos memory. The whole \dos memory is automatically mapped to
-this single descriptor at startup. This selector is the recommened way to
-access \dos memory.
-\begin{verbatim}
-  var int31error : Word;
-\end{verbatim}
-This variable holds the result of a DPMI interrupt call. Any nonzero value
-must be treated as a critical failure.
-\section{Functions and Procedures}
-\begin{functionl}{allocate\_ldt\_descriptors}{allocateldtdescriptors}
-\Declaration
-Function allocate\_ldt\_descriptors (count : Word) : Word;
-
-\Description
-Allocates a number of new descriptors.
-Parameters: 
-\begin{description}
-\item[count:\ ] specifies the number of requested unique descriptors.
-\end{description}
-Return value: The base selector.
-Notes: The descriptors allocated must be initialized by the application with
-other function calls. This function returns descriptors with a limit and
-size value set to zero. If more than one descriptor was requested, the
-function returns a base selector referencing the first of a contiguous array
-of descriptors. The selector values for subsequent descriptors in the array
-can be calculated by adding the value returned by the
-\seefl{get\_next\_selector\_increment\_value}{getnextselectorincrementvalue} 
-function.
-
-\Errors
- Check the \var{int31error} variable. 
-\SeeAlso
-
-\seefl{free\_ldt\_descriptor}{freeldtdescriptor},
-\seefl{get\_next\_selector\_increment\_value}{getnextselectorincrementvalue},
-\seefl{segment\_to\_descriptor}{segmenttodescriptor},
-\seefl{create\_code\_segment\_alias\_descriptor}{createcodesegmentaliasdescriptor},
-\seefl{set\_segment\_limit}{setsegmentlimit},
-\seefl{set\_segment\_base\_address}{setsegmentbaseaddress} 
-
-\end{functionl}
-\FPCexample{seldes}
-\begin{functionl}{allocate\_memory\_block}{allocatememoryblock}
-\Declaration
-Function allocate\_memory\_block (size:Longint) : Longint;
-
-\Description
-Allocates a block of linear memory.
-Parameters: 
-\begin{description}
-\item[size:\ ] Size of requested linear memory block in bytes.
-\end{description}
-Returned values: blockhandle - the memory handle to this memory block. Linear
-address of the requested memory.
-Notes: WARNING: According to my DPMI docs this function is not implemented
-correctly. Normally you should also get a blockhandle to this block after
-successful operation. This handle can then be used to free the memory block
-afterwards or use this handle for other purposes. Since the function isn't
-implemented correctly, and doesn't return a blockhandle, the block can't be
-deallocated and is hence unusuable !
-This function doesn't allocate any descriptors for this block, it's the
-applications resposibility to allocate and initialize for accessing this
-memory.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
- \seefl{free\_memory\_block}{freememoryblock} 
-\end{functionl}
-\begin{procedure}{copyfromdos}
-\Declaration
-Procedure copyfromdos (var addr; len : Longint);
-
-\Description
-
-Copies data from the pre-allocated \dos memory transfer buffer to the heap.
-Parameters:
-\begin{description}
-\item[addr:\ ] data to copy to.
-\item[len:\ ] number of bytes to copy to heap.
-\end{description}
-Notes:
-Can only be used in conjunction with the \dos memory transfer buffer.
-
-\Errors
-Check the \var{int31error} variable.
-\SeeAlso
-\seefl{tb\_size}{tbsize}, \seefl{transfer\_buffer}{transferbuffer}, 
-\seep{copytodos}
-\end{procedure}
-\begin{procedure}{copytodos}
-\Declaration
-Procedure copytodos (var addr; len : Longint);
-
-\Description
-Copies data from heap to the pre-allocated \dos memory buffer.
-Parameters:
-\begin{description}
-\item[addr:\ ] data to copy from.
-\item[len:\ ] number of bytes to copy to \dos memory buffer.
-\end{description}
-Notes: This function fails if you try to copy more bytes than the transfer
-buffer is in size. It can only be used in conjunction with the transfer
-buffer.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
-\seefl{tb\_size}{tbsize}, \seefl{transfer\_buffer}{transferbuffer}, 
-\seep{copyfromdos}
-\end{procedure}
-\begin{functionl}{create\_code\_segment\_alias\_descriptor}{createcodesegmentaliasdescriptor}
-\Declaration
-Function create\_code\_segment\_alias\_descriptor (seg : Word) : Word;
-
-\Description
-
-Creates a new descriptor that has the same base and limit as the specified
-descriptor.
-Parameters: 
-\begin{description}
-\item[seg:\ ] Descriptor.
-\end{description}
-Return values: The data selector (alias).
-Notes: In effect, the function returns a copy of the descriptor. The
-descriptor alias returned by this function will not track changes to the
-original descriptor. In other words, if an alias is created with this
-function, and the base or limit of the original segment is then changed, the
-two descriptors will no longer map the same memory.
-
-\Errors
-Check the \var{int31error} variable.
-\SeeAlso
- 
-\seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors},
-\seefl{set\_segment\_limit}{setsegmentlimit}, 
-\seefl{set\_segment\_base\_address}{setsegmentbaseaddress} 
-\end{functionl}
-\begin{procedure}{disable}
-\Declaration
-Procedure disable ;
-
-\Description
-Disables all hardware interrupts by execution a CLI instruction.
-Parameters: None.
-
-\Errors
-None.
-\SeeAlso
-\seep{enable}
-\end{procedure}
-\begin{procedure}{dosmemfillchar}
-\Declaration
-Procedure dosmemfillchar (seg, ofs : Word; count : Longint; c : char);
-
-\Description
-Sets a region of \dos memory to a specific byte value.
-Parameters:
-\begin{description}
-\item[seg:\ ] real mode segment.
-\item[ofs:\ ] real mode offset. 
-\item[count:\ ] number of bytes to set.
-\item[c:\ ] value to set memory to.
-\end{description}
-Notes: No range check is performed.
-
-\Errors
- None.
-\SeeAlso
- 
-\seep{dosmemput},
-\seep{dosmemget}, 
-\seep{dosmemmove}{dosmemmove}, 
-\seepl{dosmemfillword}{dosmemfillword}, 
-\seepl{seg\_move}{segmove},
-\seepl{seg\_fillchar}{segfillchar},
-\seepl{seg\_fillword}{segfillword} 
-\end{procedure}
-\FPCexample{textmess}
-\begin{procedure}{dosmemfillword}
-\Declaration
-Procedure dosmemfillword (seg,ofs : Word; count : Longint; w : Word);
-
-\Description
-Sets a region of \dos memory to a specific word value.
-Parameters: 
-\begin{description}
-\item[seg:\ ] real mode segment.
-\item[ofs:\ ] real mode offset. 
-\item[count:\ ] number of words to set.
-\item[w:\ ] value to set memory to.
-\end{description}
-Notes: No range check is performed.
-
-\Errors
- None.
-\SeeAlso
- 
-\seep{dosmemput},
-\seepl{dosmemget}{dosmemget}, 
-\seepl{dosmemmove}{dosmemmove}, 
-\seepl{dosmemfillchar}{dosmemfillchar}, 
-\seepl{seg\_move}{segmove}, 
-\seepl{seg\_fillchar}{segfillchar},
-\seepl{seg\_fillword}{segfillword} 
-\end{procedure}
-\begin{procedure}{dosmemget}
-\Declaration
-Procedure dosmemget (seg : Word; ofs : Word; var data; count : Longint);
-
-\Description
-Copies data from the \dos memory onto the heap.
-Parameters:
-\begin{description}
-\item[seg:\ ] source real mode segment.
-\item[ofs:\ ] source real mode offset.
-\item[data:\ ] destination. 
-\item[count:\ ] number of bytes to copy.
-\end{description}
-Notes: No range checking is performed.
-
-\Errors
- None. 
-\SeeAlso
-\seep{dosmemput},
-\seep{dosmemmove},
-\seep{dosmemfillchar},
-\seep{dosmemfillword},
-\seepl{seg\_move}{segmove},
-\seepl{seg\_fillchar}{segfillchar}, 
-\seepl{seg\_fillword}{segfillword}  
-\end{procedure}
-For an example, see \seefl{global\_dos\_alloc}{globaldosalloc}.
-\begin{procedure}{dosmemmove}
-\Declaration
-Procedure dosmemmove (sseg, sofs, dseg, dofs : Word; count : Longint);
-
-\Description
-Copies count bytes of data between two \dos real mode memory locations.
-Parameters:
-\begin{description}
-\item[sseg:\ ] source real mode segment. 
-\item[sofs:\ ] source real mode offset.
-\item[dseg:\ ] destination real mode segment. 
-\item[dofs:\ ] destination real mode offset.
-\item[count:\ ] number of bytes to copy.
-\end{description}
-Notes: No range check is performed in any way.
-
-\Errors
- None.
-\SeeAlso
-\seep{dosmemput}, 
-\seep{dosmemget},
-\seep{dosmemfillchar}, 
-\seep{dosmemfillword}
-\seepl{seg\_move}{segmove}, 
-\seepl{seg\_fillchar}{segfillchar},
-\seepl{seg\_fillword}{segfillword} 
-\end{procedure}
-For an example, see \seepl{seg\_fillchar}{segfillchar}.
-\begin{procedure}{dosmemput}
-\Declaration
-Procedure dosmemput (seg : Word; ofs : Word; var data; count : Longint);
-
-\Description
-Copies heap data to \dos real mode memory.
-Parameters:
-\begin{description}
-\item[seg:\ ] destination real mode segment.
-\item[ofs:\ ] destination real mode offset. 
-\item[data:\ ] source. 
-\item[count:\ ] number of bytes to copy.
-\end{description}
-Notes: No range checking is performed.
-
-\Errors
- None. 
-\SeeAlso
-\seep{dosmemget}, 
-\seep{dosmemmove},
-\seep{dosmemfillchar},
-\seep{dosmemfillword},
-\seepl{seg\_move}{segmove},
-\seepl{seg\_fillchar}{segfillchar},
-\seepl{seg\_fillword}{segfillword} 
-\end{procedure}
-For an example, see \seefl{global\_dos\_alloc}{globaldosalloc}.
-\begin{procedure}{enable}
-\Declaration
-Procedure enable ;
-
-\Description
-
-Enables all hardware interrupts by executing a STI instruction.
-Parameters: None.
-
-\Errors
-None.
-\SeeAlso
- \seep{disable} 
-\end{procedure}
-\begin{functionl}{free\_ldt\_descriptor}{freeldtdescriptor}
-\Declaration
-Function free\_ldt\_descriptor (des : Word) : boolean;
-
-\Description
-Frees a previously allocated descriptor.
-Parameters:
-\begin{description}
-\item[des:\ ] The descriptor to be freed.
-\end{description}
-Return value: \var{True} if successful, \var{False} otherwise.
-Notes: After this call this selector is invalid and must not be used for any
-memory operations anymore. Each descriptor allocated with
-\seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors} must be freed 
-individually with this function,
-even if it was previously allocated as a part of a contiguous array of
-descriptors.
-
-\Errors
-Check the \var{int31error} variable.
-\SeeAlso
-
-\seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors},
-\seefl{get\_next\_selector\_increment\_value}{getnextselectorincrementvalue} 
-
-\end{functionl}
-For an example, see 
-\seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors}.
-\begin{functionl}{free\_memory\_block}{freememoryblock}
-\Declaration
-Function free\_memory\_block (blockhandle :
-Longint) : boolean;
-
-\Description
-Frees a previously allocated memory block.
-Parameters: 
-\begin{description}
-\item{blockhandle:} the handle to the memory area to free.
-\end{description}
-Return value: \var{True} if successful, \var{false} otherwise.
-Notes: Frees memory that was previously allocated with
-\seefl{allocate\_memory\_block}{allocatememoryblock} . 
-This function doesn't free any descriptors mapped to this block, 
-it's the application's responsibility.
-
-\Errors
- Check \var{int31error} variable.
-\SeeAlso
-\seefl{allocate\_memory\_block}{allocatememoryblock} 
-\end{functionl}
-\begin{functionl}{free\_rm\_callback}{freermcallback}
-\Declaration
-Function free\_rm\_callback (var intaddr : tseginfo) : boolean;
-
-\Description
-
-Releases a real mode callback address that was previously allocated with the
-\seefl{get\_rm\_callback}{getrmcallback}  function.
-Parameters: 
-\begin{description}
-\item[intaddr:\ ] real mode address buffer returned by 
-\seefl{get\_rm\_callback}{getrmcallback} .
-\end{description}
-Return values: \var{True} if successful, \var{False} if not
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
-
-\seefl{set\_rm\_interrupt}{setrminterrupt},
-\seefl{get\_rm\_callback}{getrmcallback}
-
-\end{functionl}
-For an example, see \seefl{get\_rm\_callback}{getrmcallback}.
-\begin{functionl}{get\_cs}{getcs}
-\Declaration
-Function get\_cs  : Word;
-
-\Description
-
-Returns the cs selector.
-Parameters: None.
-Return values: The content of the cs segment register.
-
-\Errors
-None.
-\SeeAlso
- \seefl{get\_ds}{getds}, \seefl{get\_ss}{getss}
-\end{functionl}
-For an example, see \seefl{set\_pm\_interrupt}{setpminterrupt}.
-\begin{functionl}{get\_descriptor\_access\_rights}{getdescriptoraccessrights}
-\Declaration
-Function get\_descriptor\_access\_rights (d : Word) : Longint;
-
-\Description
-Gets the access rights of a descriptor.
-Parameters: 
-\begin{description}
-\item{d} selector to descriptor.
-\end{description}
-Return value: Access rights bit field.
-
-\Errors
-Check the \var{int31error} variable.
-\SeeAlso
- 
-\seefl{set\_descriptor\_access\_rights}{setdescriptoraccessrights}
-\end{functionl}
-\begin{functionl}{get\_ds}{getds}
-\Declaration
-Function get\_ds  : Word;
-
-\Description
-Returns the ds selector.
-Parameters: None.
-Return values: The content of the ds segment register.
-
-\Errors
- None.
-\SeeAlso
- \seefl{get\_cs}{getcs}, \seefl{get\_ss}{getss}
-\end{functionl}
-\begin{functionl}{get\_linear\_addr}{getlinearaddr}
-\Declaration
-Function get\_linear\_addr (phys\_addr : Longint; size : Longint) : Longint;
-
-\Description
-Converts a physical address into a linear address.
-Parameters: 
-\begin{description}
-\item [phys\_addr:\ ] physical address of device.
-\item [size:\ ] Size of region to map in bytes.
-\end{description}
-Return value: Linear address that can be used to access the physical memory.
-Notes: It's the applications resposibility to allocate and set up a
-descriptor for access to the memory. This function shouldn't be used to map
-real mode addresses.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
- 
-\seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors}, \seefl{set\_segment\_limit}{setsegmentlimit},
-\seefl{set\_segment\_base\_address}{setsegmentbaseaddress} 
-\end{functionl}
-\begin{functionl}{get\_meminfo}{getmeminfo}
-\Declaration
-Function get\_meminfo (var meminfo : tmeminfo) : boolean;
-
-\Description
- Returns information about the amount of available physical memory, linear
-address space, and disk space for page swapping.
-Parameters:
-\begin{description}
-\item[meminfo:\ ] buffer to fill memory information into.
-\end{description}
-Return values: Due to an implementation bug this function always returns
-\var{False}, but it always succeeds.
-Notes: Only the first field of the returned structure is guaranteed to
-contain a valid value. Any fields that are not supported by the DPMI host
-will be set by the host to \var{-1 (0FFFFFFFFH)} to indicate that the information
-is not available. The size of the pages used by the DPMI host can be
-obtained with the \seefl{get\_page\_size}{getpagesize}  function.
-
-\Errors
-Check the \var{int31error} variable.
-\SeeAlso
-\seefl{get\_page\_size}{getpagesize} 
-\end{functionl}
-\FPCexample{meminfo}
-\begin{functionl}{get\_next\_selector\_increment\_value}{getnextselectorincrementvalue}
-\Declaration
-Function get\_next\_selector\_increment\_value  : Word;
-
-\Description
-Returns the selector increment value when allocating multiple subsequent
-descriptors via \seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors}.
-Parameters: None.
-Return value: Selector increment value.
-Notes: Because \seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors} only returns the selector for the
-first descriptor and so the value returned by this function can be used to
-calculate the selectors for subsequent descriptors in the array.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
- \seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors}, 
-\seefl{free\_ldt\_descriptor}{freeldtdescriptor} 
-\end{functionl}
-\begin{functionl}{get\_page\_size}{getpagesize}
-\Declaration
-Function get\_page\_size  :  Longint;
-
-\Description
- Returns the size of a single memory page.
-Return value: Size of a single page in bytes.
-Notes: The returned size is typically 4096 bytes.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
- \seefl{get\_meminfo}{getmeminfo} 
-\end{functionl}
-For an example, see \seefl{get\_meminfo}{getmeminfo}.
-\begin{functionl}{get\_pm\_interrupt}{getpminterrupt}
-\Declaration
-Function get\_pm\_interrupt (vector : byte; var intaddr : tseginfo) : boolean;
-
-\Description
-Returns the address of a current protected mode interrupt handler.
-Parameters:
-\begin{description}
-\item[vector:\ ] interrupt handler number you want the address to.
-\item[intaddr:\ ] buffer to store address.
-\end{description}
-Return values: \var{True} if successful, \var{False} if not.
-Notes: The returned address is a protected mode selector:offset address.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
- \seefl{set\_pm\_interrupt}{setpminterrupt},
-\seefl{set\_rm\_interrupt}{setrminterrupt}, \seefl{get\_rm\_interrupt}{getrminterrupt} 
-\end{functionl}
-For an example, see \seefl{set\_pm\_interrupt}{setpminterrupt}.
-\begin{functionl}{get\_rm\_callback}{getrmcallback}
-\Declaration
-Function get\_rm\_callback (pm\_func : pointer; const reg : trealregs; var rmcb: tseginfo) : boolean;
-
-\Description
-
-Returns a unique real mode \var{segment:offset} address, known as a "real mode
-callback," that will transfer control from real mode to a protected mode
-procedure.
-Parameters:
-\begin{description}
-\item[pm\_func:\ ]  pointer to the protected mode callback function.
-\item[reg:\ ] supplied registers structure.
-\item[rmcb:\ ] buffer to real mode address of callback function.
-\end{description}
-Return values: \var{True} if successful, otherwise \var{False}.
-Notes: Callback addresses obtained with this function can be passed by a
-protected mode program for example to an interrupt handler, device driver,
-or TSR, so that the real mode program can call procedures within the
-protected mode program or notify the protected mode program of an event. The
-contents of the supplied regs structure is not valid after function call,
-but only at the time of the actual callback.
-
-\Errors
-Check the \var{int31error} variable.
-\SeeAlso
-\seefl{free\_rm\_callback}{freermcallback} 
-\end{functionl}
-\FPCexample{callback}
-\begin{functionl}{get\_rm\_interrupt}{getrminterrupt}
-\Declaration
-Function get\_rm\_interrupt (vector : byte; var intaddr :
-tseginfo) : boolean;
-
-\Description
-Returns the contents of the current machine's real mode interrupt vector for
-the specified interrupt.
-Parameters:
-\begin{description}
-\item[vector:\ ] interrupt vector number. 
-\item[intaddr:\ ] buffer to store real mode \var{segment:offset} address.
-\end{description}
-Return values: \var{True} if successful, \var{False} otherwise.
-Notes: The returned address is a real mode segment address, which isn't
-valid in protected mode.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
- \seefl{set\_rm\_interrupt}{setrminterrupt}, 
-\seefl{set\_pm\_interrupt}{setpminterrupt}, 
-\seefl{get\_pm\_interrupt}{getpminterrupt} 
-\end{functionl}
-\begin{functionl}{get\_run\_mode}{getrunmode}
-\Declaration
-Function get\_run\_mode  : Word;
-
-\Description
-Returns the current mode your application runs with.
-Return values: One of the constants used by this function.
-
-\Errors
-None. 
-\SeeAlso
- constants returned by \seefl{get\_run\_mode}{getrunmode}  
-\end{functionl}
-\FPCexample{getrunmd}
-\begin{functionl}{get\_segment\_base\_address}{getsegmentbaseaddress}
-\Declaration
-Function get\_segment\_base\_address  
-(d : Word) : Longint;
-
-\Description
- Returns the 32-bit linear base address from the descriptor table for the
-specified segment.
-Parameters: 
-\begin{description}
-\item[d:\ ] selector of the descriptor you want the base address of.
-\end{description}
-Return values: Linear base address of specified descriptor.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
-
-\seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors},
-\seefl{set\_segment\_base\_address}{setsegmentbaseaddress}, 
-\seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors},
-\seefl{set\_segment\_limit}{setsegmentlimit},
-\seefl{get\_segment\_limit}{getsegmentlimit} 
-
-\end{functionl}
-For an example, see 
-\seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors}.
-\begin{functionl}{get\_segment\_limit}{getsegmentlimit}
-\Declaration
-Function get\_segment\_limit (d : Word) : Longint;
-
-\Description
-Returns a descriptors segment limit.
-Parameters:
-\begin{description}
-\item [d:\ ] selector.
-\end{description}
-Return value: Limit of the descriptor in bytes.
-
-\Errors
- Returns zero if descriptor is invalid. 
-\SeeAlso
-\seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors},
-\seefl{set\_segment\_limit}{setsegmentlimit}, 
-\seefl{set\_segment\_base\_address}{setsegmentbaseaddress},
-\seefl{get\_segment\_base\_address}{getsegmentbaseaddress}, 
-
-\end{functionl}
-\begin{functionl}{get\_ss}{getss}
-\Declaration
-Function get\_ss  : Word;
-
-\Description
-
-Returns the ss selector.
-Parameters: None.
-Return values: The content of the ss segment register.
-
-\Errors
- None.
-\SeeAlso
- \seefl{get\_ds}{getds}, \seefl{get\_cs}{getcs}
-\end{functionl}
-\begin{functionl}{global\_dos\_alloc}{globaldosalloc}
-\Declaration
-Function global\_dos\_alloc (bytes : Longint) : Longint;
-
-\Description
-Allocates a block of \dos real mode memory.
-Parameters: 
-\begin{description}
-\item [bytes:\ ] size of requested real mode memory.
-\end{description}
-Return values: The low word of the returned value contains the selector to
-the allocated \dos memory block, the high word the corresponding real mode
-segment value. The offset value is always zero.
-This function allocates memory from \dos memory pool, i.e. memory below the 1
-MB boundary that is controlled by \dos. Such memory blocks are typically used
-to exchange data with real mode programs, TSRs, or device drivers. The
-function returns both the real mode segment base address of the block and
-one descriptor that can be used by protected mode applications to access the
-block. This function should only used for temporary buffers to get real mode
-information (e.g. interrupts that need a data structure in ES:(E)DI),
-because every single block needs an unique selector. The returned selector
-should only be freed by a \seefl{global\_dos\_free}{globaldosfree}  call.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
- \seefl{global\_dos\_free}{globaldosfree} 
-\end{functionl}
-\FPCexample{buffer}
-\begin{functionl}{global\_dos\_free}{globaldosfree}
-\Declaration
-Function global\_dos\_free (selector :Word) : boolean;
-
-\Description
-Frees a previously allocated \dos memory block.
-Parameters:
-\begin{description}
-\item[selector:\ ] selector to the \dos memory block.
-\end{description}
-Return value: \var{True} if successful, \var{False} otherwise.
-Notes: The descriptor allocated for the memory block is automatically freed
-and hence invalid for further use. This function should only be used for
-memory allocated by \seefl{global\_dos\_alloc}{globaldosalloc}.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
-\seefl{global\_dos\_alloc}{globaldosalloc} 
-\end{functionl}
-For an example, see \seefl{global\_dos\_alloc}{globaldosalloc}.
-\begin{function}{inportb}
-\Declaration
-Function inportb (port : Word) : byte;
-
-\Description
-Reads 1 byte from the selected I/O port.
-Parameters: 
-\begin{description}
-\item[port:\ ] the I/O port number which is read.
-\end{description}
-Return values: Current I/O port value.
-
-\Errors
- None. 
-\SeeAlso
-\seep{outportb}, \seef{inportw}, \seef{inportl}
-\end{function}
-\begin{function}{inportl}
-\Declaration
-Function inportl (port : Word) : Longint;
-
-\Description
-
-Reads 1 longint from the selected I/O port.
-Parameters: 
-\begin{description}
-\item[port:\ ] the I/O port number which is read.
-\end{description}
-Return values: Current I/O port value.
-
-\Errors
-None. 
-\SeeAlso
-\seep{outportb}, \seef{inportb}, \seef{inportw} 
-\end{function}
-\begin{function}{inportw}
-\Declaration
-Function inportw (port : Word) : Word;
-
-\Description
-
-Reads 1 word from the selected I/O port.
-Parameters: 
-\begin{description}
-\item[port:\ ] the I/O port number which is read.
-\end{description}
-Return values: Current I/O port value.
-
-\Errors
- None. 
-\SeeAlso
-\seep{outportw} \seef{inportb}, \seef{inportl} 
-\end{function}
-\begin{functionl}{lock\_code}{lockcode}
-\Declaration
-Function lock\_code (functionaddr : pointer; size : Longint) : boolean;
-
-\Description
-Locks a memory range which is in the code segment selector.
-Parameters: 
-\begin{description}
-\item[functionaddr:\ ] address of the function to be locked.
-\item[size:\ ] size in bytes to be locked.
-\end{description}
-Return values: \var{True} if successful, \var{False} otherwise.
-
-\Errors
-Check the \var{int31error} variable.
-\SeeAlso
- 
-\seefl{lock\_linear\_region}{locklinearregion},
-\seefl{lock\_data}{lockdata},
-\seefl{unlock\_linear\_region}{unlocklinearregion},
-\seefl{unlock\_data}{unlockdata},
-\seefl{unlock\_code}{unlockcode} 
-\end{functionl}
-For an example, see \seefl{get\_rm\_callback}{getrmcallback}.
-\begin{functionl}{lock\_data}{lockdata}
-\Declaration
-Function lock\_data (var data; size : Longint) : boolean;
-
-\Description
-Locks a memory range which resides in the data segment selector.
-Parameters:
-\begin{description}
-\item[data:\ ] address of data to be locked.
-\item[size:\ ] length of data to be locked.
-\end{description}
-Return values: \var{True} if successful, \var{False} otherwise.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
-
-\seefl{lock\_linear\_region}{locklinearregion},
-\seefl{lock\_code}{lockcode},
-\seefl{unlock\_linear\_region}{unlocklinearregion},
-\seefl{unlock\_data}{unlockdata},
-\seefl{unlock\_code}{unlockcode} 
-\end{functionl}
-For an example, see \seefl{get\_rm\_callback}{getrmcallback}.
-\begin{functionl}{lock\_linear\_region}{locklinearregion}
-\Declaration
-Function lock\_linear\_region (linearaddr, size : Longint) : boolean;
-
-\Description
-Locks a memory region to prevent swapping of it.
-Parameters: 
-\begin{description}
-\item[linearaddr:\ ] the linear address of the memory are to be locked.
-\item[size:\ ] size in bytes to be locked.
-\end{description}
-Return value: \var{True} if successful, False otherwise.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
-
-\seefl{lock\_data}{lockdata},
-\seefl{lock\_code}{lockcode},
-\seefl{unlock\_linear\_region}{unlocklinearregion},
-\seefl{unlock\_data}{unlockdata},
-\seefl{unlock\_code}{unlockcode}
-\end{functionl}
-\begin{procedure}{outportb}
-\Declaration
-Procedure outportb (port : Word; data : byte);
-
-\Description
-Sends 1 byte of data to the specified I/O port.
-Parameters: 
-\begin{description}
-\item[port:\ ] the I/O port number to send data to.
-\item[data:\ ] value sent to I/O port.
-\end{description}
-Return values: None.
-
-\Errors
- None. 
-\SeeAlso
-\seef{inportb}, \seep{outportl}, \seep{outportw} 
-\end{procedure}
-\FPCexample{outport}
-\begin{procedure}{outportl}
-\Declaration
-Procedure outportl (port : Word; data : Longint);
-
-\Description
-Sends 1 longint of data to the specified I/O port.
-Parameters: 
-\begin{description}
-\item[port:\ ] the I/O port number to send data to.
-\item[data:\ ] value sent to I/O port.
-\end{description}
-Return values: None.
-
-\Errors
-None. 
-\SeeAlso
-\seef{inportl}, \seep{outportw}, \seep{outportb}
-\end{procedure}
-For an example, see \seep{outportb}.
-\begin{procedure}{outportw}
-\Declaration
-Procedure outportw (port : Word; data : Word);
-
-\Description
-Sends 1 word of data to the specified I/O port.
-Parameters: 
-\begin{description}
-\item[port:\ ] the I/O port number to send data to.
-\item[data:\ ] value sent to I/O port.
-\end{description}
-Return values: None.
-
-\Errors
- None. 
-\SeeAlso
-\seef{inportw}, \seep{outportl}, \seep{outportb}
-\end{procedure}
-For an example, see \seep{outportb}.
-\begin{function}{realintr}
-\Declaration
-Function realintr (intnr: Word; var regs : trealregs) :  boolean;
-
-\Description
-Simulates an interrupt in real mode.
-Parameters:
-\begin{description}
-\item[intnr:\ ] interrupt number to issue in real mode.
-\item[regs:\ ] registers data structure.
-\end{description}
-Return values: The supplied registers data structure contains the values
-that were returned by the real mode interrupt. \var{True} if successful, \var{False} if
-not.
-Notes: The function transfers control to the address specified by the real
-mode interrupt vector of intnr. The real mode handler must return by
-executing an IRET.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
-
-\end{function}
-\FPCexample{flags}
-\begin{procedurel}{seg\_fillchar}{segfillchar}
-\Declaration
-Procedure seg\_fillchar (seg : Word; ofs : Longint; count : Longint; c : char);
-
-\Description
-
-Sets a memory area to a specific value.
-Parameters:
-\begin{description}
-\item[seg:\ ] selector to memory area.
-\item[ofs:\ ] offset to memory.
-\item[count:\ ] number of bytes to set.
-\item[c:\ ] byte data which is set.
-\end{description}
-Return values: None.
-Notes: No range check is done in any way.
-
-\Errors
- None. 
-\SeeAlso
-\seepl{seg\_move}{segmove},
-\seepl{seg\_fillword}{segfillword},
-\seepl{dosmemfillchar}{dosmemfillchar},
-\seepl{dosmemfillword}{dosmemfillword},
-\seepl{dosmemget}{dosmemget},
-\seepl{dosmemput}{dosmemput},
-\seepl{dosmemmove}{dosmemmove} 
-\end{procedurel}
-\FPCexample{vgasel}
-\begin{procedurel}{seg\_fillword}{segfillword}
-\Declaration
-Procedure seg\_fillword (seg : Word; ofs : Longint; count : Longint; w :Word);
-
-\Description
-
-Sets a memory area to a specific value.
-Parameters:
-\begin{description}
-\item[seg:\ ] selector to memory area.
-\item[ofs:\ ] offset to memory.
-\item[count:\ ] number of words to set.
-\item[w:\ ] word data which is set.
-\end{description}
-Return values: None.
-Notes: No range check is done in any way.
-
-\Errors
-None. 
-\SeeAlso
- 
-\seepl{seg\_move}{segmove},
-\seepl{seg\_fillchar}{segfillchar}, 
-\seepl{dosmemfillchar}{dosmemfillchar}, 
-\seepl{dosmemfillword}{dosmemfillword},
-\seepl{dosmemget}{dosmemget},
-\seepl{dosmemput}{dosmemput},
-\seepl{dosmemmove}{dosmemmove} 
-\end{procedurel}
-For an example, see 
-\seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors}.
-\begin{functionl}{segment\_to\_descriptor}{segmenttodescriptor}
-\Declaration
-Function segment\_to\_descriptor (seg : Word) : Word;
-
-\Description
-
-Maps a real mode segment (paragraph) address onto an descriptor that can be
-used by a protected mode program to access the same memory.
-Parameters: 
-\begin{description}
-\item [seg:\ ] the real mode segment you want the descriptor to.
-\end{description}
-Return values: Descriptor to real mode segment address.
-Notes: The returned descriptors limit will be set to 64 kB. Multiple calls
-to this function with the same segment address will return the same
-selector. Descriptors created by this function can never be modified or
-freed. Programs which need to examine various real mode addresses using the
-same selector should use the function 
-\seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors} and change
-the base address as necessary.
-
-\Errors
- Check the \var{int31error} variable. 
-\SeeAlso
-\seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors},
-\seefl{free\_ldt\_descriptor}{freeldtdescriptor},
-\seefl{set\_segment\_base\_address}{setsegmentbaseaddress} 
-
-\end{functionl}
-For an example, see \seepl{seg\_fillchar}{segfillchar}.
-\begin{procedurel}{seg\_move}{segmove}
-\Declaration
-Procedure seg\_move (sseg : Word; source : Longint; dseg : Word; dest :
-Longint; count : Longint);
-
-\Description
-Copies data between two memory locations.
-Parameters: 
-\begin{description}
-\item[sseg:\ ] source selector. 
-\item[source:\ ] source offset. 
-\item[dseg:\ ] destination selector.
-\item[dest:\ ] destination offset.
-\item[count:\ ] size in bytes to copy.
-\end{description}
-Return values: None.
-Notes: Overlapping is only checked if the source selector is equal to the
-destination selector. No range check is done.
-
-\Errors
- None.
-\SeeAlso
- 
-\seepl{seg\_fillchar}{segfillchar},
-\seepl{seg\_fillword}{segfillword},
-\seepl{dosmemfillchar}{dosmemfillchar},
-\seepl{dosmemfillword}{dosmemfillword},
-\seepl{dosmemget}{dosmemget},
-\seepl{dosmemput}{dosmemput},
-\seepl{dosmemmove}{dosmemmove} 
-\end{procedurel}
-For an example, see 
-\seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors}.
-\begin{functionl}{set\_descriptor\_access\_rights}{setdescriptoraccessrights}
-\Declaration
-Function set\_descriptor\_access\_rights (d : Word; w : Word) : Longint;
-
-\Description
-
-Sets the access rights of a descriptor.
-Parameters: 
-\begin{description}
-\item[d:\ ] selector.
-\item[w:\ ] new descriptor access rights.
-\end{description}
-Return values: This function doesn't return anything useful.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
-
-\seefl{get\_descriptor\_access\_rights}{getdescriptoraccessrights} 
-\end{functionl}
-\begin{functionl}{set\_pm\_interrupt}{setpminterrupt}
-\Declaration
-Function set\_pm\_interrupt (vector : byte; const intaddr : tseginfo) : boolean;
-
-\Description
-Sets the address of the protected mode handler for an interrupt.
-Parameters: 
-\begin{description}
-\item[vector:\ ] number of protected mode interrupt to set.
-\item[intaddr:\ ] selector:offset address to the interrupt vector.
-\end{description}
-Return values: \var{True} if successful, \var{False} otherwise.
-Notes: The address supplied must be a valid \var{selector:offset} 
-protected mode address.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
-\seefl{get\_pm\_interrupt}{getpminterrupt}, 
-\seefl{set\_rm\_interrupt}{setrminterrupt},
-\seefl{get\_rm\_interrupt}{getrminterrupt} 
-\end{functionl}
-\FPCexample{intpm}
-\begin{functionl}{set\_rm\_interrupt}{setrminterrupt}
-\Declaration
-Function set\_rm\_interrupt (vector : byte; const intaddr :
-tseginfo) : boolean;
-
-\Description
-Sets a real mode interrupt handler.
-Parameters:
-\begin{description}
-\item[vector:\ ] the interrupt vector number to set.
-\item[intaddr:\ ] address of new interrupt vector.
-\end{description}
-Return values: \var{True} if successful, otherwise \var{False}.
-Notes: The address supplied MUST be a real mode segment address, not a
-\var{selector:offset} address. So the interrupt handler must either reside in \dos
-memory (below 1 Mb boundary) or the application must allocate a real mode
-callback address with \seefl{get\_rm\_callback}{getrmcallback}.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
- 
-\seefl{get\_rm\_interrupt}{getrminterrupt}, 
-\seefl{set\_pm\_interrupt}{setpminterrupt}, \seefl{get\_pm\_interrupt}{getpminterrupt}, 
-\seefl{get\_rm\_callback}{getrmcallback} 
-\end{functionl}
-\begin{functionl}{set\_segment\_base\_address}{setsegmentbaseaddress}
-\Declaration
-Function set\_segment\_base\_address (d : Word; s : Longint) : boolean;
-
-\Description
-Sets the 32-bit linear base address of a descriptor.
-Parameters: 
-\begin{description}
-\item[d:\ ] selector.
-\item[s:\ ] new base address of the descriptor.
-\end{description}
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
-
-\seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors},
-\seefl{get\_segment\_base\_address}{getsegmentbaseaddress}, 
-\seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors}, 
-\seefl{set\_segment\_limit}{setsegmentlimit},
-\seefl{get\_segment\_base\_address}{getsegmentbaseaddress},
-\seefl{get\_segment\_limit}{getsegmentlimit} 
-
-\end{functionl}
-\begin{functionl}{set\_segment\_limit}{setsegmentlimit}
-\Declaration
-Function set\_segment\_limit (d : Word; s : Longint) : boolean;
-
-\Description
-Sets the limit of a descriptor.
-Parameters: 
-\begin{description}
-\item[d:\ ] selector.
-\item[s:\ ] new limit of the descriptor.
-\end{description}
-Return values: Returns \var{True} if successful, else \var{False}.
-Notes: The new limit specified must be the byte length of the segment - 1.
-Segment limits bigger than or equal to 1MB must be page aligned, they must
-have the lower 12 bits set.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
-\seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors},
-\seefl{set\_segment\_base\_address}{setsegmentbaseaddress},
-\seefl{get\_segment\_limit}{getsegmentlimit}, 
-\seefl{set\_segment\_limit}{setsegmentlimit} 
-
-\end{functionl}
-For an example, see 
-\seefl{allocate\_ldt\_descriptors}{allocateldtdescriptors}.
-\begin{functionl}{tb\_size}{tbsize}
-\Declaration
-Function tb\_size  : Longint;
-
-\Description
-Returns the size of the pre-allocated \dos memory buffer.
-Parameters: None.
-Return values: The size of the pre-allocated \dos memory buffer.
-Notes:
-This block always seems to be 16k in size, but don't rely on this.
-
-\Errors
-None.
-\SeeAlso
-\seefl{transfer\_buffer}{transferbuffer}, \seep{copyfromdos}
-\seep{copytodos}
-\end{functionl}
-
-\begin{functionl}{transfer\_buffer}{transferbuffer}
-\Declaration
-Function transfer\_buffer : Longint;
-\Description
-\var{transfer\_buffer} returns the offset of the transfer buffer.
-\Errors
-None.
-\SeeAlso
-\seefl{tb\_size}{tbsize}
-\end{functionl}
-
-\begin{functionl}{unlock\_code}{unlockcode}
-\Declaration
-Function unlock\_code (functionaddr : pointer; size : Longint) : boolean;
-
-\Description
-Unlocks a memory range which resides in the code segment selector.
-Parameters:
-\begin{description}
-\item[functionaddr:\ ] address of function to be unlocked. 
-\item[size:\ ] size bytes to be unlocked.
-\end{description}
-Return value: \var{True} if successful, \var{False} otherwise.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
-\seefl{unlock\_linear\_region}{unlocklinearregion},
- \seefl{unlock\_data}{unlockdata},
-\seefl{lock\_linear\_region}{locklinearregion},
-\seefl{lock\_data}{lockdata},
-\seefl{lock\_code}{lockcode} 
-\end{functionl}
-For an example, see \seefl{get\_rm\_callback}{getrmcallback}.
-\begin{functionl}{unlock\_data}{unlockdata}
-\Declaration
-Function unlock\_data (var data; size : Longint) : boolean;
-
-\Description
-Unlocks a memory range which resides in the data segment selector.
-Paramters:
-\begin{description}
-\item[data:\ ] address of memory to be unlocked. 
-\item[size:\ ] size bytes to be unlocked.
-\end{description}
-Return values: \var{True} if successful, \var{False} otherwise.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
-\seefl{unlock\_linear\_region}{unlocklinearregion},
-\seefl{unlock\_code}{unlockcode},
-\seefl{lock\_linear\_region}{locklinearregion},
-\seefl{lock\_data}{lockdata},
-\seefl{lock\_code}{lockcode} 
-\end{functionl}
-For an example, see \seefl{get\_rm\_callback}{getrmcallback}.
-\begin{functionl}{unlock\_linear\_region}{unlocklinearregion}
-\Declaration
-Function unlock\_linear\_region (linearaddr, size : Longint) : boolean;
-
-\Description
-Unlocks a previously locked linear region range to allow it to be swapped
-out again if needed.
-Parameters:
-\begin{description}
-\item[linearaddr:\ ] linear address of the memory to be unlocked. 
-\item[size:\ ] size bytes to be unlocked.
-\end{description}
-Return values: \var{True} if successful, \var{False} otherwise.
-
-\Errors
- Check the \var{int31error} variable.
-\SeeAlso
-
-\seefl{unlock\_data}{unlockdata},
-\seefl{unlock\_code}{unlockcode},
-\seefl{lock\_linear\_region}{locklinearregion},
-\seefl{lock\_data}{lockdata},
-\seefl{lock\_code}{lockcode}
-\end{functionl}
-

docs/gpm.tex

@@ -1,472 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1997, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA. 
-%
-\chapter{The GPM unit}
-\FPCexampledir{gpmex}
-\section{Introduction}
-The \file{GPM} unit implements an interface to file{libgpm}, the console
-program for mouse handling. This unit was created by Peter Vreman, and 
-is only available on \linux.
-
-When this unit is used, your program is linked to the C libraries, so
-you must take care of the C library version. Also, it will only work with
-version 1.17 or higher of the \file{libgpm} library.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Constants, types and variables
-\section{Constants, types and variables}
-\subsection{constants}
-The following constants are used to denote filenames used by the library:
-\begin{verbatim}
-_PATH_VARRUN = '/var/run/';
-_PATH_DEV    = '/dev/';
-GPM_NODE_DIR = _PATH_VARRUN;
-GPM_NODE_DIR_MODE = 0775;
-GPM_NODE_PID  = '/var/run/gpm.pid';
-GPM_NODE_DEV  = '/dev/gpmctl';
-GPM_NODE_CTL  = GPM_NODE_DEV;
-GPM_NODE_FIFO = '/dev/gpmdata';
-\end{verbatim}
-The following constants denote the buttons on the mouse:
-\begin{verbatim}
-GPM_B_LEFT   = 4;
-GPM_B_MIDDLE = 2;
-GPM_B_RIGHT  = 1;
-\end{verbatim}
-The following constants define events:
-\begin{verbatim}
-GPM_MOVE = 1;      
-GPM_DRAG = 2;
-GPM_DOWN = 4;
-GPM_UP = 8;
-GPM_SINGLE = 16;
-GPM_DOUBLE = 32;
-GPM_TRIPLE = 64;
-GPM_MFLAG = 128;
-GPM_HARD = 256;
-GPM_ENTER = 512;
-GPM_LEAVE = 1024;
-\end{verbatim}
-The following constants are used in defining margins:
-\begin{verbatim}
-GPM_TOP = 1;
-GPM_BOT = 2;
-GPM_LFT = 4;
-GPM_RGT = 8;
-\end{verbatim}
-
-% Types
-\subsection{Types}
-The following general types are defined:
-\begin{verbatim}
-  TGpmEtype = longint;
-  TGpmMargin = longint;
-\end{verbatim}
-The following type describes an event; it is passed in many of the gpm
-functions.
-\begin{verbatim}
-PGpmEvent = ^TGpmEvent;
-TGpmEvent = record
-  buttons : byte;
-  modifiers : byte;
-  vc : word;
-  dx : word;
-  dy : word;
-  x : word;
-  y : word;
-  EventType : TGpmEType;
-  clicks : longint;
-  margin : TGpmMargin;
-end;
-TGpmHandler=function(var event:TGpmEvent;clientdata:pointer):longint;cdecl;
-\end{verbatim}
-The following types are used in connecting to the \file{gpm} server:
-\begin{verbatim}
-PGpmConnect = ^TGpmConnect;
-TGpmConnect = record
-  eventMask : word;
-  defaultMask : word;
-  minMod : word;
-  maxMod : word;
-  pid : longint;
-  vc : longint;
-end;
-\end{verbatim}
-The following type is used to define {\em regions of interest}
-\begin{verbatim}
-PGpmRoi = ^TGpmRoi;
-TGpmRoi = record
-  xMin : integer;
-  xMax : integer;
-  yMin : integer;
-  yMax : integer;
-  minMod : word;
-  maxMod : word;
-  eventMask : word;
-  owned : word;
-  handler : TGpmHandler;
-  clientdata : pointer;
-  prev : PGpmRoi;
-  next : PGpmRoi;
-end;
-\end{verbatim}
-
-% Variables
-\subsection{Variables}
-The following variables are imported from the \var{gpm} library
-\begin{verbatim}
-gpm_flag           : longint;cvar;external;
-gpm_fd             : longint;cvar;external;
-gpm_hflag          : longint;cvar;external;
-gpm_morekeys       : Longbool;cvar;external;
-gpm_zerobased      : Longbool;cvar;external;
-gpm_visiblepointer : Longbool;cvar;external;
-gpm_mx             : longint;cvar;external;
-gpm_my             : longint;cvar;external;
-gpm_timeout        : TTimeVal;cvar;external;
-_gpm_buf           : array[0..0] of char;cvar;external;
-_gpm_arg           : ^word;cvar;external;
-gpm_handler        : TGpmHandler;cvar;external;
-gpm_data           : pointer;cvar;external;
-gpm_roi_handler    : TGpmHandler;cvar;external;
-gpm_roi_data       : pointer;cvar;external;
-gpm_roi            : PGpmRoi;cvar;external;
-gpm_current_roi    : PGpmRoi;cvar;external;
-gpm_consolefd      : longint;cvar;external;
-Gpm_HandleRoi      : TGpmHandler;cvar;external;
-\end{verbatim}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Functions and procedures
-\section{Functions and procedures}
-
-\begin{functionl}{Gpm\_AnyDouble}{GpmAnyDouble}
-\Declaration
-function Gpm\_AnyDouble(EventType : longint) : boolean;
-\Description
-\var{Gpm\_AnyDouble} returns \var{True} if \var{EventType} contains
-the \var{GPM\_DOUBLE} flag, \var{False} otherwise.
-\Errors
-None.
-\SeeAlso
-\seefl{Gpm\_StrictSingle}{GpmStrictSingle},
-\seefl{Gpm\_AnySingle}{GpmAnySingle},
-\seefl{Gpm\_StrictDouble}{GpmStrictDouble},
-\seefl{Gpm\_StrictTriple}{GpmStrictTriple},
-\seefl{Gpm\_AnyTriple}{GpmAnyTriple}
-\end{functionl}
-
-\begin{functionl}{Gpm\_AnySingle}{GpmAnySingle}
-\Declaration
-function Gpm\_AnySingle(EventType : longint) : boolean;
-\Description
-\var{Gpm\_AnySingle} returns \var{True} if \var{EventType} contains
-the \var{GPM\_SINGLE} flag, \var{False} otherwise. 
-\Errors
-\SeeAlso
-\seefl{Gpm\_StrictSingle}{GpmStrictSingle},
-\seefl{Gpm\_AnyDoubmle}{GpmAnyDouble},
-\seefl{Gpm\_StrictDouble}{GpmStrictDouble},
-\seefl{Gpm\_StrictTriple}{GpmStrictTriple},
-\seefl{Gpm\_AnyTriple}{GpmAnyTriple}
-\end{functionl}
-
-\begin{functionl}{Gpm\_AnyTriple}{GpmAnyTriple}
-\Declaration
-function Gpm\_AnyTriple(EventType : longint) : boolean;
-\Description
-\Errors
-\SeeAlso
-\seefl{Gpm\_StrictSingle}{GpmStrictSingle},
-\seefl{Gpm\_AnyDoubmle}{GpmAnyDouble},
-\seefl{Gpm\_StrictDouble}{GpmStrictDouble},
-\seefl{Gpm\_StrictTriple}{GpmStrictTriple},
-\seefl{Gpm\_AnySingle}{GpmAnySingle}
-\end{functionl}
-
-\begin{functionl}{Gpm\_Close}{GpmClose}
-\Declaration
-function Gpm\_Close:longint;cdecl;external;
-\Description
-\var{Gpm\_Close} closes the current connection, and pops the connection
-stack; this means that the previous connection becomes active again.
-
-The function returns -1 if the current connection is not the last one,
-and it returns 0 if the current connection is the last one.
-\Errors
-None.
-\SeeAlso
-\seefl{Gpm\_Open}{GpmOpen}
-\end{functionl}
-
-for an example, see \seefl{Gpm\_GetEvent}{GpmGetEvent}.
-
-\begin{functionl}{Gpm\_FitValues}{GpmFitValues}
-\Declaration
-function Gpm\_FitValues(var x,y:longint):longint;cdecl;external;
-\Description
-\var{Gpm\_fitValues} changes \var{x} and \var{y} so they fit in the visible
-screen. The actual mouse pointer is not affected by this function.
-\Errors
-None.
-\SeeAlso
-\seefl{Gpm\_FitValuesM}{GpmFitValuesM},
-\end{functionl}
-
-\begin{functionl}{Gpm\_FitValuesM}{GpmFitValuesM}
-\Declaration
-function Gpm\_FitValuesM(var x,y:longint; margin:longint):longint;cdecl;external;
-\Description
-\var{Gpm\_FitValuesM} chnages \var{x} and \var{y} so they fit in the margin
-indicated by \var{margin}. If \var{margin} is -1, then the values are fitted
-to the screen. The actual mouse pointer is not affected by this function.
-\Errors
-None.
-\SeeAlso
-\seefl{Gpm\_FitValues}{GpmFitValues},
-\end{functionl}
-
-\begin{functionl}{Gpm\_GetEvent}{GpmGetEvent}
-\Declaration
-function Gpm\_GetEvent(var Event:TGpmEvent):longint;cdecl;external;
-\Description
-\var{Gpm\_GetEvent} Reads an event from the file descriptor \var{gpm\_fd}.
-This file is only for internal use and should never be called by a client
-application. 
-
-It returns 1 on succes, and -1 on failue.
-\Errors
-On error, -1 is returned. 
-\SeeAlso
-seefl{Gpm\_GetSnapshot}{GpmGetSnapshot}
-\end{functionl}
-
-\FPCexample{gpmex}
-
-\begin{functionl}{Gpm\_GetLibVersion}{GpmGetLibVersion}
-\Declaration
-function Gpm\_GetLibVersion(var where:longint):pchar;cdecl;external;
-\Description
-\var{Gpm\_GetLibVersion} returns a pointer to a version string, and returns
-in \var{where} an integer representing the version. The version string
-represents the version of the gpm library.
-
-The return value is a pchar, which should not be dealloacted, i.e. it is not
-on the heap.
-\Errors
-None.
-\SeeAlso
-\seefl{Gpm\_GetServerVersion}{GpmGetServerVersion}
-\end{functionl}
-
-\begin{functionl}{Gpm\_GetServerVersion}{GpmGetServerVersion}
-\Declaration
-function Gpm\_GetServerVersion(var where:longint):pchar;cdecl;external;
-\Description
-\var{Gpm\_GetServerVersion} returns a pointer to a version string, and 
-returns in \var{where} an integer representing the version. The version string
-represents the version of the gpm server program.
-
-The return value is a pchar, which should not be dealloacted, i.e. it is not
-on the heap.
-\Errors
-If the gpm program is not present, then the function returns \var{Nil}
-\SeeAlso
-\seefl{Gpm\_GetLibVersion}{GpmGetLibVersion}
-\end{functionl}
-
-\begin{functionl}{Gpm\_GetSnapshot}{GpmGetSnapshot}
-\Declaration
-function Gpm\_GetSnapshot(var Event:TGpmEvent):longint;cdecl;external;
-\Description
-\var{Gpm\_GetSnapshot} returns the picture that the server has of the 
-current situation in \var{Event}. 
-This call will not read the current situation from the mouse file
-descriptor, but returns a buffered version.
-The meaning of the fields is as follows:
-\begin{description}
-\item[x,y] current position of the cursor.
-\item[dx,dy] size of the window.
-\item[vc] number of te virtual console.
-\item[modifiers] keyboard shift state.
-\item[buttons] buttons which are currently pressed.
-\item[clicks] number of clicks (0,1 or 2).
-\end{description}
-The function returns the number of mouse buttons, or -1 if this information
-is not available.
-\Errors
-None.
-\SeeAlso
-\seefl{Gpm\_GetEvent}{GpmGetEvent}
-\end{functionl}
-
-\begin{functionl}{Gpm\_LowerRoi}{GpmLowerRoi}
-\Declaration
-function Gpm\_LowerRoi(which:PGpmRoi; after:PGpmRoi):PGpmRoi;cdecl;external;
-\Description
-\var{Gpm\_LowerRoi} lowers the region of interest \var{which} after
-\var{after}. If \var{after} is \var{Nil}, the region of interest is moved to
-the bottom of the stack.
-
-The return value is the new top of the region-of-interest stack.
-\Errors
-None.
-\SeeAlso
-\seefl{Gpm\_RaiseRoi}{GpmRaiseRoi},
-\seefl{Gpm\_PopRoi}{GpmPopRoi},
-\seefl{Gpm\_PushRoi}{GpmPopRoi} 
-\end{functionl}
-
-\begin{functionl}{Gpm\_Open}{GpmOpen}
-\Declaration
-function Gpm\_Open(var Conn:TGpmConnect; Flag:longint):longint;cdecl;external;
-\Description
-\var{Gpm\_Open} opens a new connection to the mouse server. The connection
-is described by the fields of the \var{conn} record:
-\begin{description}
-\item[EventMask] A bitmask of the events the program wants to receive.
-\item[DefaultMask] A bitmask to tell the library which events get their
-default treatment (text selection).
-\item[minMod] the minimum amount of modifiers needed by the program.
-\item[maxMod] the maximum amount of modifiers needed by the program.
-\end{description}
-if \var{Flag} is 0, then the application only receives events that come from
-its own terminal device. If it is negative it will receive all events. If
-the value is positive then it is considered a console number to which to
-connect.
-
-The return value is -1 on error, or the file descriptor used to communicate
-with the client. Under an X-Term the return value is -2.
-\Errors
-On Error, the return value is -1.
-\SeeAlso
-\seefl{Gpm\_Open}{GpmOpen}
-\end{functionl}
-
-for an example, see \seefl{Gpm\_GetEvent}{GpmGetEvent}.
-
-\begin{functionl}{Gpm\_PopRoi}{GpmPopRoi}
-\Declaration
-function Gpm\_PopRoi(which:PGpmRoi):PGpmRoi;cdecl;external;
-\Description
-\var{Gpm\_PopRoi} pops the topmost region of interest from the stack.
-It returns the next element on the stack, or \var{Nil} if the current 
-element was the last one.
-\Errors
-None.
-\SeeAlso
-\seefl{Gpm\_RaiseRoi}{GpmRaiseRoi},
-\seefl{Gpm\_LowerRoi}{GpmLowerRoi}, 
-\seefl{Gpm\_PushRoi}{GpmPopRoi} 
-\end{functionl}
-
-\begin{functionl}{Gpm\_PushRoi}{GpmPushRoi}
-\Declaration
-function Gpm\_PushRoi(x1:longint; y1:longint; X2:longint; Y2:longint; mask:longint; fun:TGpmHandler; xtradata:pointer):PGpmRoi;cdecl;external;
-\Description
-\var{Gpm\_PushRoi} puts a new {\em region of interest} on the stack.
-The region of interest is defined by a rectangle described by the corners
-\var{(X1,Y1)} and \var{(X2,Y2)}. 
-
-The \var{mask} describes which events the handler {fun} will handle;
-\var{ExtraData} will be put in the \var{xtradata} field of the {TGPM\_Roi} 
-record passed to the \var{fun} handler.
-\Errors
-None.
-\SeeAlso
-\seefl{Gpm\_RaiseRoi}{GpmRaiseRoi},
-\seefl{Gpm\_PopRoi}{GpmPopRoi}, 
-\seefl{Gpm\_LowerRoi}{GpmLowerRoi} 
-\end{functionl}
-
-\begin{functionl}{Gpm\_RaiseRoi}{GpmRaiseRoi}
-\Declaration
-function Gpm\_RaiseRoi(which:PGpmRoi; before:PGpmRoi):PGpmRoi;cdecl;external;
-\Description
-\var{Gpm\_RaiseRoi} raises the {\em region of interest} \var{which} till it
-is on top of region \var{before}. If \var{before} is nil then the region is
-put on top of the stack. The returned value is the top of the stack.
-\Errors
-None.
-\SeeAlso
-\seefl{Gpm\_PushRoi}{GpmPushRoi},
-\seefl{Gpm\_PopRoi}{GpmPopRoi}, 
-\seefl{Gpm\_LowerRoi}{GpmLowerRoi} 
-\end{functionl}
-
-\begin{functionl}{Gpm\_Repeat}{GpmRepeat}
-\Declaration
-function Gpm\_Repeat(millisec:longint):longint;cdecl;external;
-\Description
-\var{Gpm\_Repeat} returns 1 of no mouse event arrives in the next
-\var{millisec} miiliseconds, it returns 0 otherwise.
-\Errors
-None.
-\SeeAlso
-\seefl{Gpm\_GetEvent}{GpmGetEvent}
-\end{functionl}
-
-\begin{functionl}{Gpm\_StrictDouble}{GpmStrictDouble}
-\Declaration
-function Gpm\_StrictDouble(EventType : longint) : boolean;
-\Description
-\var{Gpm\_StrictDouble} returns true if \var{EventType} contains only a 
-doubleclick event, \var{False} otherwise.
-\Errors
-None.
-\SeeAlso
-\seefl{Gpm\_StrictSingle}{GpmStrictSingle},
-\seefl{Gpm\_AnyTriple}{GpmAnyTriple},
-\seefl{Gpm\_AnyDouble}{GpmAnyDouble},
-\seefl{Gpm\_StrictTriple}{GpmStrictTriple},
-\seefl{Gpm\_AnySingle}{GpmAnySingle}
-\end{functionl}
-
-\begin{functionl}{Gpm\_StrictSingle}{GpmStrictSingle}
-\Declaration
-function Gpm\_StrictSingle(EventType : longint) : boolean;
-\Description
-\var{Gpm\_StrictDouble} returns \var{True} if \var{EventType} contains only a 
-singleclick event, \var{False} otherwise. 
-\Errors
-None.
-\SeeAlso
-\seefl{Gpm\_AnyTriple}{GpmAnyTriple},
-\seefl{Gpm\_StrictDouble}{GpmStrictDouble},
-\seefl{Gpm\_AnyDouble}{GpmAnyDouble}, 
-\seefl{Gpm\_StrictTriple}{GpmStrictTriple},
-\seefl{Gpm\_AnySingle}{GpmAnySingle}
-\end{functionl}
-
-\begin{functionl}{Gpm\_StrictTriple}{GpmStrictTriple}
-\Declaration
-function Gpm\_StrictTriple(EventType : longint) : boolean;
-\Description
-\var{Gpm\_StrictTriple} returns true if \var{EventType} contains only a
-triple click event, \var{False} otherwise.
-\Errors
-None.
-\SeeAlso
-\seefl{Gpm\_AnyTriple}{GpmAnyTriple},
-\seefl{Gpm\_StrictDouble}{GpmStrictDouble},
-\seefl{Gpm\_AnyDouble}{GpmAnyDouble}, 
-\seefl{Gpm\_StrictSingle}{GpmStrictSingle},
-\seefl{Gpm\_AnySingle}{GpmAnySingle}
-\end{functionl}

docs/graph.tex

@@ -1,1571 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1997, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA. 
-%
-% Documentation for the 'Graph' unit of Free Pascal.
-% Michael Van Canneyt, July 1997
-\chapter{The GRAPH unit.}
-\FPCexampledir{graphex}
-This document describes the \var{GRAPH} unit for Free Pascal, for all
-platforms. The unit was first written for \dos by Florian kl\"ampfl, but was
-later completely rewritten by Carl-Eric Codere to be completely portable.
-The unit is provided for compatibility only: It is recommended to use more
-modern graphical systems. The graph unit will allow to recompile old
-programs, they will work to some extent, but if the application has 
-heavy graphical needs, it's recommended to use another set of graphical
-routines, suited to the platform the program should work on.
-
-This chapter is divided in 4 sections. 
-\begin{itemize}
-\item The first section gives an introduction to the graph unit.
-\item The second section lists the pre-defined constants, types and variables. 
-\item The second section describes the functions which appear in the
-interface part of the \file{GRAPH} unit.
-\item The last part describes some system-specific issues.
-
-\end{itemize}
-\section{Introduction}
-\label{se:Introduction}
-\subsection{Requirements}
-The unit Graph exports functions and procedures for graphical output.
-It requires at least a VGA-compatible Card or a VGA-Card with software-driver
-(min. \textbf{512Kb} video memory).
-\subsection{A word about mode selection}
-The graph unit was implemented for compatibility with the old \tp graph
-unit. For this reason, the mode constants as they were defined in the
-\tp graph unit are retained. 
-
-However, since
-\begin{enumerate}
-\item Video cards have evolved very much
-\item Free Pascal runs on multiple platforms
-\end{enumerate}
-it was decided to implement new mode and graphic driver constants, 
-which are more independent of the specific platform the program runs on.
-
-In this section we give a short explanation of the new mode system. the
-following drivers were defined:
-\begin{verbatim}
-D1bit = 11;
-D2bit = 12;
-D4bit = 13;
-D6bit = 14;  { 64 colors Half-brite mode - Amiga }
-D8bit = 15;
-D12bit = 16; { 4096 color modes HAM mode - Amiga }
-D15bit = 17;
-D16bit = 18;
-D24bit = 19; { not yet supported }
-D32bit = 20; { not yet supported }
-D64bit = 21; { not yet supported }
-
-lowNewDriver = 11;
-highNewDriver = 21;
-\end{verbatim}
-Each of these drivers specifies a desired color-depth. 
-
-The following modes have been defined:
-\begin{verbatim}
-detectMode = 30000;
-m320x200 = 30001;  
-m320x256 = 30002; { amiga resolution (PAL) }
-m320x400 = 30003; { amiga/atari resolution }
-m512x384 = 30004; { mac resolution }
-m640x200 = 30005; { vga resolution }
-m640x256 = 30006; { amiga resolution (PAL) }
-m640x350 = 30007; { vga resolution }
-m640x400 = 30008;
-m640x480 = 30009;
-m800x600 = 30010;
-m832x624 = 30011; { mac resolution }
-m1024x768 = 30012;
-m1280x1024 = 30013;
-m1600x1200 = 30014;
-m2048x1536 = 30015;
-
-lowNewMode = 30001;
-highNewMode = 30015;
-\end{verbatim}
-These modes start at 30000 because Borland specified that the mode number
-should be ascending with increasing X resolution, and the new constants 
-shouldn't interfere with the old ones.
-
-The above constants can be used to set a certain color depth and resultion,
-as demonstrated in the following example:
-
-\FPCexample{inigraph1}
-
-If other modes than the ones above are supported by the graphics card,
-you will not be able to select them with this mechanism.
-
-For this reason, there is also a 'dynamic' mode number, which is assigned at
-run-time. This number increases with increasing X resolution. It can be
-queried with the \var{getmoderange} call. This call will return the range
-of modes which are valid for a certain graphics driver. The numbers are
-guaranteed to be consecutive, and can be used to search for a certain 
-resolution, as in the following example:
-
-\FPCexample{inigraph2}
-
-
-Thus, the \var{getmoderange} function can be used to detect all available 
-modes and drivers, as in the following example:
-
-\FPCexample{modrange}
-
-\section{Constants, Types and Variables}
-\subsection{Types}
-\begin{verbatim}
-ArcCoordsType = record
- X,Y,Xstart,Ystart,Xend,Yend : Integer;
-end;
-FillPatternType = Array [1..8] of Byte;
-FillSettingsType = Record
- Pattern,Color : Word
-end;
-LineSettingsType = Record
-  LineStyle,Pattern, Width : Word;
-end;
-RGBRec = packed record
-  Red: smallint;
-  Green: smallint;
-  Blue : smallint;
-end;
-PaletteType = record
-  Size   : longint;
-  Colors : array[0..MaxColors] of RGBRec;
-end;
-PointType = Record
-  X,Y : Integer;
-end;
-TextSettingsType = Record
- Font,Direction, CharSize, Horiz, Vert : Word
-end;
-ViewPortType = Record
-  X1,Y1,X2,Y2 : Integer;
-  Clip : Boolean
-end;
-\end{verbatim}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Functions and procedures by category
-\section{Function list by category}
-What follows is a listing of the available functions, grouped by category.
-For each function there is a reference to the page where you can find the
-function.
-\subsection{Initialization}
-Initialization of the graphics screen.
-\begin{funclist}
-\procref{ClearDevice}{Empty the graphics screen}
-\procref{CloseGraph}{Finish drawing session, return to text mode}
-\procref{DetectGraph}{Detect graphical modes}
-\procref{GetAspectRatio}{Get aspect ratio of screen}
-\procref{GetModeRange}{Get range of valid modes for current driver}
-\procref{GraphDefaults}{Set defaults}
-\funcref{GetDriverName}{Return name of graphical driver}
-\funcref{GetGraphMode}{Return current or last used graphics mode}
-\funcref{GetMaxMode}{Get maximum mode for current driver}
-\funcref{GetModeName}{Get name of current mode}
-\funcref{GraphErrorMsg}{String representation of graphical error}
-\funcref{GraphResult}{Result of last drawing operation}
-\procref{InitGraph}{Initialize graphics drivers}
-\funcref{InstallUserDriver}{Install a new driver}
-\funcref{RegisterBGIDriver}{Register a new driver}
-\procref{RestoreCRTMode}{Go back to text mode}
-\procref{SetGraphBufSize}{Set buffer size for graphical operations}
-\procref{SetGraphMode}{Set graphical mode}
-\end{funclist}
-
-\subsection{screen management}
-General drawing screen management functions.
-\begin{funclist}
-\procref{ClearViewPort}{Clear the current viewport}
-\procref{GetImage}{Copy image from screen to memory}
-\funcref{GetMaxX}{Get maximum X coordinate}
-\funcref{GetMaxY}{Get maximum Y coordinate}
-\funcref{GetX}{Get current X position}
-\funcref{GetY}{Get current Y position}
-\funcref{ImageSize}{Get size of selected image}
-\procref{GetViewSettings}{Get current viewport settings}
-\procref{PutImage}{Copy image from memory to screen}
-\procref{SetActivePage}{Set active video page}
-\procref{SetAspectRatio}{Set aspect ratio for drawing routines}
-\procref{SetViewPort}{Set current viewport}
-\procref{SetVisualPage}{Set visual page}
-\procref{SetWriteMode}{Set write mode for screen operations}
-\end{funclist}
-
-\subsection{Color management}
-All functions related to color management.
-\begin{funclist}
-\funcref{GetBkColor}{Get current background color}
-\funcref{GetColor}{Get current foreground color}
-\procref{GetDefaultPalette}{Get default palette entries}
-\funcref{GetMaxColor}{Get maximum valid color}
-\funcref{GetPaletteSize}{Get size of palette for current mode}
-\funcref{GetPixel}{Get color of selected pixel}
-\procref{GetPalette}{Get palette entry}
-\procref{SetAllPallette}{Set all colors in palette}
-\procref{SetBkColor}{Set background color}
-\procref{SetColor}{Set foreground color}
-\procref{SetPalette}{Set palette entry}
-\procref{SetRGBPalette}{Set palette entry with RGB values}
-\end{funclist}
-
-\subsection{Drawing primitives}
-Functions for simple drawing.
-\begin{funclist}
-\procref{Arc}{Draw an arc}
-\procref{Circle}{Draw a complete circle}
-\procref{DrawPoly}{Draw a polygone with N points}
-\procref{Ellipse}{Draw an ellipse}
-\procref{GetArcCoords}{Get arc coordinates}
-\procref{GetLineSettings}{Get current line drawing settings}
-\procref{Line}{Draw line between 2 points}
-\procref{LineRel}{Draw line relative to current position}
-\procref{LineTo}{Draw line from current position to absolute position}
-\procref{MoveRel}{Move cursor relative to current position}
-\procref{MoveTo}{Move cursor to absolute position}
-\procref{PieSlice}{Draw a pie slice}
-\procref{PutPixel}{Draw 1 pixel}
-\procref{Rectangle}{Draw a non-filled rectangle}
-\procref{Sector}{Draw a sector}
-\procref{SetLineStyle}{Set current line drawing style}
-\end{funclist}
-
-\subsection{Filled drawings}
-Functions for drawing filled regions.
-\begin{funclist}
-\procref{Bar3D}{Draw a filled 3D-style bar}
-\procref{Bar}{Draw a filled rectangle}
-\procref{FloodFill}{Fill starting from coordinate}
-\procref{FillEllipse}{Draw a filled ellipse}
-\procref{FillPoly}{Draw a filled polygone}
-\procref{GetFillPattern}{Get current fill pattern}
-\procref{GetFillSettings}{Get current fill settings}
-\procref{SetFillPattern}{Set current fill pattern}
-\procref{SetFillStyle}{Set current fill settings}
-\end{funclist}
-
-\subsection{Text and font handling}
-Functions to set texts on the screen.
-\begin{funclist}
-\procref{GetTextSettings}{Get current text settings}
-\funcref{InstallUserFont}{Install a new font}
-\procref{OutText}{Write text at current cursor position}
-\procref{OutTextXY}{Write text at coordinates X,Y}
-\funcref{RegisterBGIFont}{Register a new font}
-\procref{SetTextJustify}{Set text justification}
-\procref{SetTextStyle}{Set text style}
-\procref{SetUserCharSize}{Set text size}
-\funcref{TextHeight}{Calculate height of text}
-\funcref{TextWidth}{Calculate width of text}
-\end{funclist}
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Functions and procedures
-\section{Functions and procedures}
-
-\begin{procedure}{Arc}
-\Declaration
-Procedure Arc (X,Y : Integer; start,stop, radius : Word);
-
-\Description
- \var{Arc} draws part of a circle with center at \var{(X,Y)}, radius
-\var{radius}, starting from angle \var{start}, stopping at angle \var{stop}.
-These  angles are measured
-counterclockwise.
-\Errors
-None.
-\SeeAlso
-\seep{Circle},\seep{Ellipse} 
-\seep{GetArcCoords},\seep{PieSlice}, \seep{Sector}
-\end{procedure}
-
-\begin{procedure}{Bar}
-\Declaration
-Procedure Bar (X1,Y1,X2,Y2 : Integer);
-
-\Description
-Draws a rectangle with corners at \var{(X1,Y1)} and \var{(X2,Y2)} 
-and fills it with the current color and fill-style.
-\Errors
-None.
-\SeeAlso
-\seep{Bar3D}, 
-\seep{Rectangle}
-\end{procedure}
-
-\begin{procedure}{Bar3D}
-\Declaration
-Procedure Bar3D (X1,Y1,X2,Y2 : Integer; depth : Word; Top : Boolean);
-
-\Description
-Draws a 3-dimensional Bar  with corners at \var{(X1,Y1)} and \var{(X2,Y2)} 
-and fills it with the current color and fill-style.
-\var{Depth} specifies the number of pixels used to show the depth of the
-bar.
-If \var{Top} is true; then a 3-dimensional top is drawn.
-\Errors
-None.
-\SeeAlso
-\seep{Bar}, \seep{Rectangle}
-\end{procedure}
-
-\begin{procedure}{Circle}
-\Declaration
-Procedure Circle (X,Y : Integer; Radius : Word);
-
-\Description
- \var{Circle} draws part of a circle with center at \var{(X,Y)}, radius
-\var{radius}.
-\Errors
-None.
-\SeeAlso
-\seep{Ellipse},\seep{Arc}
-\seep{GetArcCoords},\seep{PieSlice}, \seep{Sector}
-\end{procedure}
-
-\begin{procedure}{ClearDevice}
-\Declaration
-Procedure ClearDevice ;
-
-\Description
-Clears the graphical screen (with the current
-background color), and sets the pointer at \var{(0,0)}
-\Errors
-None.
-\SeeAlso
-\seep{ClearViewPort}, \seep{SetBkColor}
-\end{procedure}
-
-\begin{procedure}{ClearViewPort}
-\Declaration
-Procedure ClearViewPort ;
-
-\Description
-Clears the current viewport. The current background color is used as filling
-color. The pointer is set at
-\var{(0,0)}
-\Errors
-None.
-\SeeAlso
-\seep{ClearDevice},\seep{SetViewPort}, \seep{SetBkColor}
-\end{procedure}
-
-\begin{procedure}{CloseGraph}
-\Declaration
-Procedure CloseGraph ;
-
-\Description
-Closes the graphical system, and restores the
-screen modus which was active before the graphical modus was
-activated.
-\Errors
-None.
-\SeeAlso
-\seep{InitGraph}
-\end{procedure}
-
-\begin{procedure}{DetectGraph}
-\Declaration
-Procedure DetectGraph (Var Driver, Modus : Integer);
-
-\Description
- Checks the hardware in the PC and determines the driver and screen-modus to
-be used. These are returned in \var{Driver} and \var{Modus}, and can be fed
-to \var{InitGraph}. 
-See the \var{InitGraph} for a list of drivers and modi.
-\Errors
-None.
-\SeeAlso
-\seep{InitGraph}
-\end{procedure}
-
-\begin{procedure}{DrawPoly}
-\Declaration
-Procedure DrawPoly (NumberOfPoints : Word; Var PolyPoints;
-
-\Description
-
-Draws a polygone with \var{NumberOfPoints} corner points, using the
-current color and line-style. PolyPoints is an array of type \var{PointType}.
-
-\Errors
-None.
-\SeeAlso
-\seep{Bar}, seep{Bar3D}, \seep{Rectangle}
-\end{procedure}
-
-\begin{procedure}{Ellipse}
-\Declaration
-Procedure Ellipse (X,Y : Integer; Start,Stop,XRadius,YRadius : Word);
-
-\Description
- \var{Ellipse} draws part of an ellipse with center at \var{(X,Y)}.
-\var{XRadius} and \var{Yradius} are the horizontal and vertical radii of the
-ellipse. \var{Start} and \var{Stop} are the starting and stopping angles of
-the part of the ellipse. They are measured counterclockwise from the X-axis 
-(3 o'clock is equal to 0 degrees). Only positive angles can be specified.
-\Errors
-None.
-\SeeAlso
-\seep{Arc} \seep{Circle}, \seep{FillEllipse}
-\end{procedure}
-
-\begin{procedure}{FillEllipse}
-\Declaration
-Procedure FillEllipse (X,Y : Integer; Xradius,YRadius: Word);
-
-\Description
- \var{Ellipse} draws an ellipse with center at \var{(X,Y)}.
-\var{XRadius} and \var{Yradius} are the horizontal and vertical radii of the
-ellipse. The ellipse is filled with the current color and fill-style.
-\Errors
-None.
-\SeeAlso
-\seep{Arc} \seep{Circle},
-\seep{GetArcCoords},\seep{PieSlice}, \seep{Sector}
-\end{procedure}
-
-\begin{procedure}{FillPoly}
-\Declaration
-Procedure FillPoly (NumberOfPoints : Word; Var PolyPoints);
-
-\Description
-
-Draws a polygone with \var{NumberOfPoints} corner points and fills it
-using the current color and line-style. 
-PolyPoints is an array of type \var{PointType}.
-
-\Errors
-None.
-\SeeAlso
-\seep{Bar}, seep{Bar3D}, \seep{Rectangle}
-\end{procedure}
-
-\begin{procedure}{FloodFill}
-\Declaration
-Procedure FloodFill (X,Y : Integer; BorderColor : Word);
-
-\Description
-
-Fills the area containing the point \var{(X,Y)}, bounded by the color
-\var{BorderColor}.
-\Errors
-None
-\SeeAlso
-\seep{SetColor}, \seep{SetBkColor}
-\end{procedure}
-
-\begin{procedure}{GetArcCoords}
-\Declaration
-Procedure GetArcCoords (Var ArcCoords : ArcCoordsType);
-
-\Description
-\var{GetArcCoords} returns the coordinates of the latest \var{Arc} or
-\var{Ellipse} call.
-\Errors
-None.
-\SeeAlso
-\seep{Arc}, \seep{Ellipse}
-\end{procedure}
-
-\begin{procedure}{GetAspectRatio}
-\Declaration
-Procedure GetAspectRatio (Var Xasp,Yasp : Word);
-
-\Description
-\var{GetAspectRatio} determines the effective resolution of the screen. The aspect ration can
-the be calculated as \var{Xasp/Yasp}.
-\Errors
-None.
-\SeeAlso
-\seep{InitGraph},\seep{SetAspectRatio}
-\end{procedure}
-
-\begin{function}{GetBkColor}
-\Declaration
-Function GetBkColor  : Word;
-
-\Description
-\var{GetBkColor} returns the current background color (the palette
-entry).
-\Errors
-None.
-\SeeAlso
-\seef{GetColor},\seep{SetBkColor}
-\end{function}
-
-\begin{function}{GetColor}
-\Declaration
-Function GetColor  : Word;
-
-\Description
-\var{GetColor} returns the current drawing color (the palette
-entry).
-\Errors
-None.
-\SeeAlso
-\seef{GetColor},\seep{SetBkColor}
-\end{function}
-
-\begin{procedure}{GetDefaultPalette}
-\Declaration
-Procedure GetDefaultPalette (Var Palette : PaletteType);
-
-\Description
-Returns the
-current palette in \var{Palette}.
-\Errors
-None.
-\SeeAlso
-\seef{GetColor}, \seef{GetBkColor}
-\end{procedure}
-
-\begin{function}{GetDriverName}
-\Declaration
-Function GetDriverName  : String;
-
-\Description
-\var{GetDriverName} returns a string containing the name of the
-current driver.
-\Errors
-None.
-\SeeAlso
-\seef{GetModeName}, \seep{InitGraph}
-\end{function}
-
-\begin{procedure}{GetFillPattern}
-\Declaration
-Procedure GetFillPattern (Var FillPattern : FillPatternType);
-
-\Description
-\var{GetFillPattern} returns an array with the current fill-pattern  in \var{FillPattern}
-\Errors
-None
-\SeeAlso
-\seep{SetFillPattern}
-\end{procedure}
-
-\begin{procedure}{GetFillSettings}
-\Declaration
-Procedure GetFillSettings (Var FillInfo : FillSettingsType);
-
-\Description
-\var{GetFillSettings} returns the current fill-settings in
-\var{FillInfo}
-\Errors
-None.
-\SeeAlso
-\seep{SetFillPattern}
-\end{procedure}
-
-\begin{function}{GetGraphMode}
-\Declaration
-Function GetGraphMode  : Integer;
-
-\Description
-\var{GetGraphMode} returns the current graphical modus
-\Errors
-None.
-\SeeAlso
-\seep{InitGraph}
-\end{function}
-
-\begin{procedure}{GetImage}
-\Declaration
-Procedure GetImage (X1,Y1,X2,Y2 : Integer, Var Bitmap;
-
-\Description
-\var{GetImage}
-Places a copy of the screen area \var{(X1,Y1)} to \var{X2,Y2} in \var{BitMap}
-\Errors
-Bitmap must have enough room to contain the image.
-\SeeAlso
-\seef{ImageSize},
-\seep{PutImage}
-\end{procedure}
-
-\begin{procedure}{GetLineSettings}
-\Declaration
-Procedure GetLineSettings (Var LineInfo : LineSettingsType);
-
-\Description
-\var{GetLineSettings} returns the current Line settings in
-\var{LineInfo}
-\Errors
-None.
-\SeeAlso
-\seep{SetLineStyle}
-\end{procedure}
-
-\begin{function}{GetMaxColor}
-\Declaration
-Function GetMaxColor  : Word;
-
-\Description
-\var{GetMaxColor} returns the maximum color-number which can be 
-set with \var{SetColor}. Contrary to \tp, this color isn't always 
-guaranteed to be white (for instance in 256+ color modes).
-\Errors
-None.
-\SeeAlso
-\seep{SetColor},
-\seef{GetPaletteSize}
-\end{function}
-
-\begin{function}{GetMaxMode}
-\Declaration
-Function GetMaxMode  : Word;
-
-\Description
-\var{GetMaxMode} returns the highest modus for
-the current driver.
-\Errors
-None.
-\SeeAlso
-\seep{InitGraph}
-\end{function}
-
-\begin{function}{GetMaxX}
-\Declaration
-Function GetMaxX  : Word;
-
-\Description
-\var{GetMaxX} returns the maximum horizontal screen
-length
-\Errors
-None.
-\SeeAlso
-\seef{GetMaxY}
-\end{function}
-
-\begin{function}{GetMaxY}
-\Declaration
-Function GetMaxY  : Word;
-
-\Description
-\var{GetMaxY} returns the maximum number of screen
-lines
-\Errors
-None.
-\SeeAlso
-\seef{GetMaxY}
-\end{function}
-
-\begin{function}{GetModeName}
-\Declaration
-Function GetModeName (Var modus : Integer) : String;
-
-\Description
-
-Returns a string with the name of modus
-\var{Modus}
-\Errors
-None.
-\SeeAlso
-\seef{GetDriverName}, \seep{InitGraph}
-\end{function}
-
-\begin{procedure}{GetModeRange}
-\Declaration
-Procedure GetModeRange (Driver : Integer; \\ LoModus, HiModus: Integer);
-\Description
-\var{GetModeRange} returns the Lowest and Highest modus of the currently
-installed driver. If no modes are supported for this driver, HiModus
-will be -1.
-\Errors
-None.
-\SeeAlso
-\seep{InitGraph}
-\end{procedure}
-
-\begin{procedure}{GetPalette}
-\Declaration
-Procedure GetPalette (Var Palette : PaletteType);
-
-\Description
-\var{GetPalette} returns in \var{Palette} the current palette.
-\Errors
-None.
-\SeeAlso
-\seef{GetPaletteSize}, \seep{SetPalette}
-\end{procedure}
-
-\begin{function}{GetPaletteSize}
-\Declaration
-Function GetPaletteSize  : Word;
-
-\Description
-\var{GetPaletteSize} returns the maximum
-number of entries in the current palette.
-\Errors
-None.
-\SeeAlso
-\seep{GetPalette},
-\seep{SetPalette}
-\end{function}
-
-\begin{function}{GetPixel}
-\Declaration
-Function GetPixel (X,Y : Integer) : Word;
-
-\Description
-\var{GetPixel} returns the color
-of the point at \var{(X,Y)} 
-\Errors
-None.
-\SeeAlso
-
-\end{function}
-
-\begin{procedure}{GetTextSettings}
-\Declaration
-Procedure GetTextSettings (Var TextInfo : TextSettingsType);
-
-\Description
-\var{GetTextSettings} returns the current text style settings : The font,
-direction, size and placement as set with \var{SetTextStyle} and
-\var{SetTextJustify}
-\Errors
-None.
-\SeeAlso
-\seep{SetTextStyle}, \seep{SetTextJustify}
-\end{procedure}
-
-\begin{procedure}{GetViewSettings}
-\Declaration
-Procedure GetViewSettings (Var ViewPort : ViewPortType);
-
-\Description
-\var{GetViewSettings} returns the current viewport and clipping settings in
-\var{ViewPort}.
-\Errors
-None.
-\SeeAlso
-\seep{SetViewPort}
-\end{procedure}
-
-\begin{function}{GetX}
-\Declaration
-Function GetX  : Integer;
-
-\Description
-\var{GetX} returns the X-coordinate of the current position of
-the graphical pointer
-\Errors
-None.
-\SeeAlso
-\seef{GetY}
-\end{function}
-
-\begin{function}{GetY}
-\Declaration
-Function GetY  : Integer;
-
-\Description
-\var{GetY} returns the Y-coordinate of the current position of
-the graphical pointer
-\Errors
-None.
-\SeeAlso
-\seef{GetX}
-\end{function}
-
-\begin{procedure}{GraphDefaults}
-\Declaration
-Procedure GraphDefaults ;
-
-\Description
-\var{GraphDefaults} resets all settings for viewport, palette,
-foreground and background pattern, line-style and pattern, filling style,
-filling color and pattern, font, text-placement and
-text size.
-\Errors
-None.
-\SeeAlso
-\seep{SetViewPort}, \seep{SetFillStyle}, \seep{SetColor},
-\seep{SetBkColor}, \seep{SetLineStyle}
-\end{procedure}
-
-\begin{function}{GraphErrorMsg}
-\Declaration
-Function GraphErrorMsg (ErrorCode : Integer) : String;
-
-\Description
-\var{GraphErrorMsg}
-returns a string describing the error \var{Errorcode}. This string can be
-used to let the user know what went wrong.
-\Errors
-None.
-\SeeAlso
-\seef{GraphResult}
-\end{function}
-
-\begin{function}{GraphResult}
-\Declaration
-Function GraphResult  : Integer;
-
-\Description
-\var{GraphResult} returns an error-code for
-the last graphical operation. If the returned value is zero, all went well.
-A value different from zero means an error has occurred.
-besides all operations which draw something on the screen, 
-the following procedures also can produce a \var{GraphResult} different from
-zero:
-
-\begin{itemize}
-\item \seef{InstallUserFont}
-\item \seep{SetLineStyle}
-\item \seep{SetWriteMode}
-\item \seep{SetFillStyle}
-\item \seep{SetTextJustify}
-\item \seep{SetGraphMode}
-\item \seep{SetTextStyle}
-\end{itemize}
-
-\Errors
-None.
-\SeeAlso
-\seef{GraphErrorMsg}
-\end{function}
-
-\begin{function}{ImageSize}
-\Declaration
-Function ImageSize (X1,Y1,X2,Y2 : Integer) : Word;
-
-\Description
-\var{ImageSize} returns
-the number of bytes needed to store the image in the rectangle defined by
-\var{(X1,Y1)} and \var{(X2,Y2)}.
-\Errors
-None.
-\SeeAlso
-\seep{GetImage}
-\end{function}
-
-\begin{procedure}{InitGraph}
-\Declaration
-Procedure InitGraph (var GraphDriver,GraphModus : integer;\\
-const PathToDriver : string);
-\Description
-\var{InitGraph} initializes the \var{graph} package.
-\var{GraphDriver} has two valid values: \var{GraphDriver=0} which
-performs an auto detect and initializes the highest possible mode with the most
-colors. 1024x768x64K is the highest possible resolution supported by the
-driver, if you need a higher resolution, you must edit \file{MODES.PPI}. 
-If you need another mode, then set \var{GraphDriver} to a value different
-from zero
-and \var{graphmode} to the mode you wish (VESA modes where 640x480x256
-is \var {101h} etc.).
-\var{PathToDriver} is only needed, if you use the BGI fonts from
-Borland. Free Pascal does not offer BGI fonts like Borland, these must be
-obtained separately. 
-\Errors
-None.
-\SeeAlso
-Introduction, (page \pageref{se:Introduction}),
-\seep{DetectGraph}, \seep{CloseGraph}, \seef{GraphResult}
-\end{procedure}
-Example:
-
-\begin{verbatim}
-var 
-   gd,gm : integer; 
-   PathToDriver : string; 
-begin 
-   gd:=detect; { highest possible resolution } 
-   gm:=0; { not needed, auto detection } 
-   PathToDriver:='C:\PP\BGI'; { path to BGI fonts, 
-                                drivers aren't needed } 
-   InitGraph(gd,gm,PathToDriver); 
-   if GraphResult<>grok then 
-     halt; ..... { whatever you need } 
-   CloseGraph; { restores the old graphics mode } 
-end.
-\end{verbatim}
-
-\begin{function}{InstallUserDriver}
-\Declaration
-Function InstallUserDriver (DriverPath : String; \\AutoDetectPtr: Pointer) : Integer;
-
-\Description
-\var{InstallUserDriver} 
-adds the device-driver \var{DriverPath} to the list of .BGI
-drivers. \var{AutoDetectPtr} is a pointer to a possible auto-detect function.
-\Errors
-None.
-\SeeAlso
-\seep{InitGraph}, \seef{InstallUserFont}
-\end{function}
-
-\begin{function}{InstallUserFont}
-\Declaration
-Function InstallUserFont (FontPath : String) : Integer;
-
-\Description
-\var{InstallUserFont} adds the font in \var{FontPath} to the list of fonts
-of the .BGI system.
-\Errors
-None.
-\SeeAlso
-\seep{InitGraph}, \seef{InstallUserDriver}
-\end{function}
-
-\begin{procedure}{Line}
-\Declaration
-Procedure Line (X1,Y1,X2,Y2 : Integer);
-
-\Description
-\var{Line} draws a line starting from
-\var{(X1,Y1} to \var{(X2,Y2)}, in the current line style and color. The
-current position is put to \var{(X2,Y2)}
-\Errors
-None.
-\SeeAlso
-\seep{LineRel},\seep{LineTo}
-\end{procedure}
-
-\begin{procedure}{LineRel}
-\Declaration
-Procedure LineRel (DX,DY : Integer);
-
-\Description
-\var{LineRel} draws a line starting from
-the current pointer position to the point\var{(DX,DY}, \textbf{relative} to the
-current position, in the current line style and color. The Current Position
-is set to the endpoint of the line.
-\Errors
-None.
-\SeeAlso
-\seep{Line}, \seep{LineTo}
-\end{procedure}
-
-\begin{procedure}{LineTo}
-\Declaration
-Procedure LineTo (DX,DY : Integer);
-
-\Description
-\var{LineTo} draws a line starting from
-the current pointer position to the point\var{(DX,DY}, \textbf{relative} to the
-current position, in the current line style and color. The Current position
-is set to the end of the line.
-\Errors
-None.
-\SeeAlso
-\seep{LineRel},\seep{Line}
-\end{procedure}
-
-\begin{procedure}{MoveRel}
-\Declaration
-Procedure MoveRel (DX,DY : Integer;
-
-\Description
-\var{MoveRel} moves the pointer to the
-point \var{(DX,DY)}, relative to the current pointer
-position
-\Errors
-None.
-\SeeAlso
-\seep{MoveTo}
-\end{procedure}
-
-\begin{procedure}{MoveTo}
-\Declaration
-Procedure MoveTo (X,Y : Integer;
-
-\Description
-\var{MoveTo} moves the pointer to the
-point \var{(X,Y)}.
-\Errors
-None.
-\SeeAlso
-\seep{MoveRel}
-\end{procedure}
-
-\begin{procedure}{OutText}
-\Declaration
-Procedure OutText (Const TextString : String);
-
-\Description
-\var{OutText} puts \var{TextString} on the screen, at the current pointer
-position, using the current font and text settings. The current position is
-moved to the end of the text.
-\Errors
-None.
-\SeeAlso
-\seep{OutTextXY}
-\end{procedure}
-
-\begin{procedure}{OutTextXY}
-\Declaration
-Procedure OutTextXY (X,Y : Integer; Const TextString : String);
-
-\Description
-\var{OutText} puts \var{TextString} on the screen, at position \var{(X,Y)},
-using the current font and text settings. The current position is
-moved to the end of the text.
-\Errors
-None.
-\SeeAlso
-\seep{OutText}
-\end{procedure}
-
-\begin{procedure}{PieSlice}
-\Declaration
-Procedure PieSlice (X,Y : Integer; \\ Start,Stop,Radius : Word);
-
-\Description
-\var{PieSlice}
-draws and fills a sector of a circle with center \var{(X,Y)} and radius 
-\var{Radius}, starting at angle \var{Start} and ending at angle \var{Stop}.
-\Errors
-None.
-\SeeAlso
-\seep{Arc}, \seep{Circle}, \seep{Sector}
-\end{procedure}
-
-\begin{procedure}{PutImage}
-\Declaration
-Procedure PutImage (X1,Y1 : Integer; Var Bitmap; How : word) ;
-
-\Description
-\var{PutImage}
-Places the bitmap in \var{Bitmap} on the screen at \var{(X1,Y1)}. \var{How}
-determines how the bitmap will be placed on the screen. Possible values are :
-
-\begin{itemize}
-\item CopyPut
-\item XORPut
-\item ORPut
-\item AndPut
-\item NotPut
-\end{itemize}
-\Errors
-None
-\SeeAlso
-\seef{ImageSize},\seep{GetImage}
-\end{procedure}
-
-\begin{procedure}{PutPixel}
-\Declaration
-Procedure PutPixel (X,Y : Integer; Color : Word);
-
-\Description
-Puts a point at
-\var{(X,Y)} using color \var{Color}
-\Errors
-None.
-\SeeAlso
-\seef{GetPixel}
-\end{procedure}
-
-\begin{procedure}{Rectangle}
-\Declaration
-Procedure Rectangle (X1,Y1,X2,Y2 : Integer);
-
-\Description
-Draws a rectangle with
-corners at \var{(X1,Y1)} and \var{(X2,Y2)}, using the current color and
-style.
-\Errors
-None.
-\SeeAlso
-\seep{Bar}, \seep{Bar3D}
-\end{procedure}
-
-\begin{function}{RegisterBGIDriver}
-\Declaration
-Function RegisterBGIDriver (Driver : Pointer) : Integer;
-
-\Description
-Registers a user-defined BGI driver
-\Errors
-None.
-\SeeAlso
-\seef{InstallUserDriver},
-\seef{RegisterBGIFont}
-\end{function}
-
-\begin{function}{RegisterBGIFont}
-\Declaration
-Function RegisterBGIFont (Font : Pointer) : Integer;
-
-\Description
-Registers a user-defined BGI driver
-\Errors
-None.
-\SeeAlso
-\seef{InstallUserFont},
-\seef{RegisterBGIDriver}
-\end{function}
-
-\begin{procedure}{RestoreCRTMode}
-\Declaration
-Procedure RestoreCRTMode ;
-
-\Description
-Restores the screen modus which was active before
-the graphical modus was started.
-
-To get back to the graph mode you were last in, you can use
-\var{SetGraphMode(GetGraphMode)}
-\Errors
-None.
-\SeeAlso
-\seep{InitGraph}
-\end{procedure}
-
-\begin{procedure}{Sector}
-\Declaration
-Procedure Sector (X,Y : Integer; \\ Start,Stop,XRadius,YRadius : Word);
-
-\Description
-\var{Sector}
-draws and fills a sector of an ellipse  with center \var{(X,Y)} and radii 
-\var{XRadius} and \var{YRadius}, starting at angle \var{Start} and ending at angle \var{Stop}.
-\Errors
-None.
-\SeeAlso
-\seep{Arc}, \seep{Circle}, \seep{PieSlice}
-\end{procedure}
-
-\begin{procedure}{SetActivePage}
-\Declaration
-Procedure SetActivePage (Page : Word);
-
-\Description
-Sets \var{Page} as the active page 
-for all graphical output.
-\Errors
-None.
-\SeeAlso
-
-\end{procedure}
-
-\begin{procedure}{SetAllPallette}
-\Declaration
-Procedure SetAllPallette (Var Palette);
-
-\Description
-Sets the current palette to
-\var{Palette}. \var{Palette} is an untyped variable, usually pointing to a
-record of type \var{PaletteType}
-\Errors
-None.
-\SeeAlso
-\seep{GetPalette}
-\end{procedure}
-
-\begin{procedure}{SetAspectRatio}
-\Declaration
-Procedure SetAspectRatio (Xasp,Yasp : Word);
-
-\Description
-Sets the aspect ratio of the
-current screen to \var{Xasp/Yasp}.
-\Errors
-None
-\SeeAlso
-\seep{InitGraph}, \seep{GetAspectRatio}
-\end{procedure}
-
-\begin{procedure}{SetBkColor}
-\Declaration
-Procedure SetBkColor (Color : Word);
-
-\Description
-Sets the background color to
-\var{Color}.
-\Errors
-None.
-\SeeAlso
-\seef{GetBkColor}, \seep{SetColor}
-\end{procedure}
-
-\begin{procedure}{SetColor}
-\Declaration
-Procedure SetColor (Color : Word);
-
-\Description
-Sets the foreground color to
-\var{Color}.
-\Errors
-None.
-\SeeAlso
-\seef{GetColor}, \seep{SetBkColor}
-\end{procedure}
-
-\begin{procedure}{SetFillPattern}
-\Declaration
-Procedure SetFillPattern (FillPattern : FillPatternType,\\ Color : Word);
-
-\Description
-\var{SetFillPattern} sets the current fill-pattern to \var{FillPattern}, and
-the filling color to \var{Color}
-The pattern is an 8x8 raster, corresponding to the 64 bits in
-\var{FillPattern}.
-\Errors
-None
-\SeeAlso
-\seep{GetFillPattern}, \seep{SetFillStyle}
-\end{procedure}
-
-\begin{procedure}{SetFillStyle}
-\Declaration
-Procedure SetFillStyle (Pattern,Color : word);
-
-\Description
-\var{SetFillStyle} sets the filling pattern and color to one of the
-predefined filling patterns. \var{Pattern} can be one of the following predefined
-constants :
-
-\begin{itemize}
-\item \var{EmptyFill  } Uses backgroundcolor.
-\item \var{SolidFill  } Uses filling color
-\item \var{LineFill   } Fills with horizontal lines.
-\item \var{ltSlashFill} Fills with lines from left-under to top-right.
-\item \var{SlashFill  } Idem as previous, thick lines.
-\item \var{BkSlashFill} Fills with thick lines from left-Top to bottom-right.
-\item \var{LtBkSlashFill} Idem as previous, normal lines.
-\item \var{HatchFill}  Fills with a hatch-like pattern.
-\item \var{XHatchFill} Fills with a hatch pattern, rotated 45 degrees.
-\item \var{InterLeaveFill} 
-\item \var{WideDotFill} Fills with dots, wide spacing.
-\item \var{CloseDotFill} Fills with dots, narrow spacing.
-\item \var{UserFill} Fills with a user-defined pattern.
-\end{itemize}
-
-\Errors
-None.
-\SeeAlso
-\seep{SetFillPattern}
-\end{procedure}
-
-\begin{procedure}{SetGraphBufSize}
-\Declaration
-Procedure SetGraphBufSize (BufSize : Word);
-
-\Description
-\var{SetGraphBufSize} is a dummy function which does not do 
-anything; it is no longer needed.
-\Errors
-None.
-\SeeAlso
-
-\end{procedure}
-
-\begin{procedure}{SetGraphMode}
-\Declaration
-Procedure SetGraphMode (Mode : Integer);
-
-\Description
-\var{SetGraphMode} sets the graphical mode and clears the screen.
-\Errors
-None.
-\SeeAlso
-\seep{InitGraph}
-\end{procedure}
-
-\begin{procedure}{SetLineStyle}
-\Declaration
-Procedure SetLineStyle (LineStyle,Pattern,Width :
-Word);
-
-\Description
-\var{SetLineStyle}
-sets the drawing style for lines. You can specify a \var{LineStyle} which is
-one of the following pre-defined constants:
-
-\begin{itemize}
-\item \var{Solidln=0;} draws a solid line.
-\item \var{Dottedln=1;} Draws a dotted line.
-\item \var{Centerln=2;} draws a non-broken centered line.
-\item \var{Dashedln=3;} draws a dashed line.
-\item \var{UserBitln=4;} Draws a User-defined bit pattern.
-\end{itemize}
-If \var{UserBitln} is specified then \var{Pattern} contains the bit pattern.
-In all another cases, \var{Pattern} is ignored. The parameter \var{Width} 
-indicates how thick the line should be. You can specify one of the following
-pre-defined constants:
-
-\begin{itemize}
-\item \var{NormWidth=1}
-\item \var{ThickWidth=3}
-\end{itemize}
-
-\Errors
-None.
-\SeeAlso
-\seep{GetLineSettings}
-\end{procedure}
-
-\begin{procedure}{SetPalette}
-\Declaration
-Procedure SetPalette (ColorNr : Word; NewColor : ShortInt);
-
-\Description
-\var{SetPalette} changes the \var{ColorNr}-th entry in the palette to
-\var{NewColor}
-\Errors
-None.
-\SeeAlso
-\seep{SetAllPallette},\seep{SetRGBPalette}
-\end{procedure}
-
-\begin{procedure}{SetRGBPalette}
-\Declaration
-Procedure SetRGBPalette (ColorNr,Red,Green,Blue : Integer);
-
-\Description
-\var{SetRGBPalette} sets the \var{ColorNr}-th entry in the palette to the
-color with RGB-values \var{Red, Green Blue}.
-\Errors
-None.
-\SeeAlso
-\seep{SetAllPallette},
-\seep{SetPalette}
-\end{procedure}
-
-\begin{procedure}{SetTextJustify}
-\Declaration
-Procedure SetTextJustify (Horizontal,Vertical : Word);
-
-\Description
-\var{SetTextJustify} controls the placement of new text, relative to the 
-(graphical) cursor position. \var{Horizontal} controls horizontal placement, and can be
-one of the following pre-defined constants:
-
-\begin{itemize}
-\item \var{LeftText=0;} Text is set left of the pointer.
-\item \var{CenterText=1;} Text is set centered horizontally on the pointer.
-\item \var{RightText=2;} Text is set to the right of the pointer.
-\end{itemize}
-\var{Vertical} controls the vertical placement of the text, relative to the
-(graphical) cursor position. Its value can be one of the following
-pre-defined constants :
-
-\begin{itemize}
-\item \var{BottomText=0;} Text is placed under the pointer.
-\item \var{CenterText=1;} Text is placed centered vertically on the pointer.
-\item \var{TopText=2;}Text is placed above the pointer.
-\end{itemize}
-
-\Errors
-None.
-\SeeAlso
-\seep{OutText}, \seep{OutTextXY}
-\end{procedure}
-
-\begin{procedure}{SetTextStyle}
-\Declaration
-Procedure SetTextStyle (Font,Direction,Magnitude : Word);
-
-\Description
-\var{SetTextStyle} controls the style of text to be put on the screen.
-pre-defined constants for \var{Font} are:
-
-\begin{verbatim}
-DefaultFont   = 0;
-TriplexFont   = 1;
-SmallFont     = 2;
-SansSerifFont = 3;
-GothicFont    = 4;
-ScriptFont    = 5;
-SimpleFont    = 6;
-TSCRFont      = 7;
-LCOMFont      = 8;
-EuroFont      = 9;
-BoldFont      = 10;
-\end{verbatim}
-Pre-defined constants for \var{Direction} are :
-
-\begin{itemize}
-\item \var{HorizDir=0;}
-\item \var{VertDir=1;}
-\end{itemize}
-\Errors
-None.
-\SeeAlso
-\seep{GetTextSettings} 
-\end{procedure}
-
-\begin{procedure}{SetUserCharSize}
-\Declaration
-Procedure SetUserCharSize (Xasp1,Xasp2,Yasp1,Yasp2 : Word);
-
-\Description
-Sets the width and height of vector-fonts. The horizontal size is given
-by \var{Xasp1/Xasp2}, and the vertical size by \var{Yasp1/Yasp2}.
-\Errors
-None.
-\SeeAlso
-\seep{SetTextStyle}
-\end{procedure}
-
-\begin{procedure}{SetViewPort}
-\Declaration
-Procedure SetViewPort (X1,Y1,X2,Y2 : Integer; Clip : Boolean);
-
-\Description
-Sets the current graphical viewport (window) to the rectangle defined by
-the top-left corner \var{(X1,Y1)} and the bottom-right corner \var{(X2,Y2)}.
-If \var{Clip} is true, anything drawn outside the viewport (window) will be
-clipped (i.e. not drawn). Coordinates specified after this call are relative
-to the top-left corner of the viewport.
-\Errors
-None.
-\SeeAlso
-\seep{GetViewSettings}
-\end{procedure}
-
-\begin{procedure}{SetVisualPage}
-\Declaration
-Procedure SetVisualPage (Page : Word);
-
-\Description
-\var{SetVisualPage} sets the video page to page number \var{Page}. 
-\Errors
-None
-\SeeAlso
-\seep{SetActivePage}
-\end{procedure}
-
-\begin{procedure}{SetWriteMode}
-\Declaration
-Procedure SetWriteMode (Mode : Integer);
-
-\Description
-\var{SetWriteMode} controls the drawing of lines on the screen. It controls
-the binary operation used when drawing lines on the screen. \var{Mode} can
-be one of the following pre-defined constants:
-
-\begin{itemize}
-\item CopyPut=0;
-\item XORPut=1;
-\end{itemize}
-\Errors
-None.
-\SeeAlso
-
-\end{procedure}
-
-\begin{function}{TextHeight}
-\Declaration
-Function TextHeight (S : String) : Word;
-
-\Description
-\var{TextHeight} returns the height (in pixels) of the string \var{S} in
-the current font and text-size.
-
-\Errors
-None.
-\SeeAlso
-\seef{TextWidth}
-\end{function}
-
-\begin{function}{TextWidth}
-\Declaration
-Function TextWidth (S : String) : Word;
-
-\Description
-\var{TextHeight} returns the width (in pixels) of the string \var{S} in
-the current font and text-size.
-\Errors
-None.
-\SeeAlso
-\seef{TextHeight}
-\end{function}
-
-% Target specific issues.
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Target specific issues}                                                                                                                                                                                                                                                               
-In what follows we describe some things that are different on the various
-platforms:
-
-\subsection{\dos}
-VESA modes (i.e., anything but 320x200x256 and 640x480x16) do not work 
-under most installations of Windows NT, Windows 2000 and Windows XP. 
-They also do not work for some people under Windows 98 and Windows ME, 
-depending on their graphics drivers. However, the graph unit cannot 
-detect this, because no errors are returned from the system. 
-In such cases, the screen simply turns black, or will show garbage.
-
-Nothing can be done about this, the reason is missing or buggy
-support in the graphics drivers of the operating system.
-
-\subsection{\windows}
-The windows version of the Graph units is not very performant. It works,
-thus allowing to port old TP programs to Windows, but that is all what can
-be expected from it. Further, it is windowed only: A separate window is
-opened in which the graphics are displayed. This means that the normal 
-keyboard/mouse handling as provided by the crt and/or keyboard/mouse units
-wil not work in the graphical window. If keyboard and mouse input are needed
-the winmouse and the wincrt unit should be used instead. 
-To hide the console window, compile with the
-\begin{verbatim}
-{$apptype gui}
-\end{verbatim}
-switch.
-
-Further, the following extra modes are available:
-\begin{verbatim}
-mLargestWindow16  = $f0;
-mLargestWindow256 = $f1;
-mLargestWindow32k = $f2;
-mLargestWindow64k = $f3;
-mLargestWindow16M = $f4;
-mMaximizedWindow16 = $f5;
-mMaximizedWindow256 = $f6;
-mMaximizedWindow32k = $f7;
-mMaximizedWindow64k = $f8;
-mMaximizedWindow16M = $f9;
-\end{verbatim}
-
-\subsection{\linux}
-There are several issues on Linux that need to be taken care of:
-\begin{enumerate}
-\item The Linux version of the \file{Graph} unit uses the \file{libvga} 
-library. This library works on the console, not under X.
-\item If you get an error similar to
-\begin{verbatim}
-/usr/bin/ld: cannot find -lvga
-\end{verbatim}
-This can mean one of two things: either libvga is not installed properly, or
-the directory where it is installed is not in the linker path. To remedy the
-former, you should install both the libvga package and libvga-devel package
-(or compile and install from scratch).
-
-To remedy the latter, you should add the path to the compiler command-line
-using the \var{-Fl} option.
-\item Programs using \file{libvga} need root privileges to run. 
-You can make them setuid root with the following command:
-\begin{verbatim}
-chown root.root myprogram
-chmod u+s myprogram
-\end{verbatim}
-The libvga library will give up the root privileges after it is initialized.
-\item there is an experimental version of the Graphics library available that
-uses GGI to do all the drawing, but it is not well tested. It's called
-\file{ggigraph} and is distributed in source form only.
-\item Do not use the CRT unit together with the Graph unit: the console may
-end up in an unusable state. Instead, the \file{ncurses} unit may function 
-fine.
-\end{enumerate}

docs/heaptrc.tex

@@ -1,235 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1998, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA. 
-%
-\chapter{The HEAPTRC unit.}
-\FPCexampledir{heapex}
-
-This chapter describes the HEAPTRC unit for \fpc. It was written by 
-Pierre Muller. It is system independent, and works on all supported systems.
-
-\section{Purpose}
-
-The HEAPTRC unit can be used to debug your memory allocation/deallocation.
-It keeps track of the calls to getmem/freemem, and, implicitly, of
-New/Dispose statements.
-
-When the program exits, or when you request it explicitly.
-It displays the total memory used, and then dumps a list of blocks that
-were allocated but not freed. It also displays where the memory was
-allocated.
-
-If there are any inconsistencies, such as memory blocks being allocated
-or freed twice, or a memory block that is released but with wrong size,
-this will be displayed also.
-
-The information that is stored/displayed can be customized using
-some constants.
-
-
-\section{Usage}
-
-All that you need to do is to include \file{heaptrc} in the uses clause
-of your program. Make sure that it is the first unit in the clause,
-otherwise memory allocated in initialization code of units that precede the
-heaptrc unit will not be accounted for, causing an incorrect memory usage
-report.
-
-If you use the \var{-gh} switch, the compiler will insert the unit by itself,
-so you don't have to include it in your uses clause.
-
-The following example shows how to use the heaptrc unit.
-
-\FPCexample{heapex}
-
-This is the memory dump shown when running this program:
-\begin{verbatim}
-Marked memory at 0040FA50 invalid
-Wrong size : 128 allocated 64 freed
-  0x00408708
-  0x0040CB49
-  0x0040C481
-Call trace for block 0x0040FA50 size 128
-  0x0040CB3D
-  0x0040C481
-\end{verbatim}
-
-If you use the \file{lineinfo} unit (or use the \var{-gl} switch) as well,
-then \file{heaptrc} will also give you the filenames and line-numbers of
-the procedures in the backtrace:
-\begin{verbatim}
-Marked memory at 00410DA0 invalid
-Wrong size : 128 allocated 64 freed
-  0x004094B8
-  0x0040D8F9  main,  line 25 of heapex.pp
-  0x0040D231
-Call trace for block 0x00410DA0 size 128
-  0x0040D8ED  main,  line 23 of heapex.pp
-  0x0040D231
-\end{verbatim}
-If lines without filename/line-number occur, this means there is a unit which
-has no debug info included.
-
-\section{Constants, Types and variables}
-
-The \var{FillExtraInfoType} is a procedural type used in the
-\seep{SetExtraInfo} call.
-
-\begin{verbatim}
-type
-    FillExtraInfoType = procedure(p : pointer);
-\end{verbatim}
-The following typed constants allow to fine-tune the standard dump of the
-memory usage by \seep{DumpHeap}:
-
-\begin{verbatim}
-const
-  tracesize = 8;
-  quicktrace : boolean = true;
-  HaltOnError : boolean = true;
-  keepreleased : boolean = false;
-  add_tail : boolean = true;
-  usecrc : boolean = true
-\end{verbatim}
-
-\var{Tracesize} specifies how many levels of calls are displayed of the 
-call stack during the memory dump. If you specify \var{keepreleased:=True}
-then half the \var{TraceSize} is reserved for the \var{GetMem} call stack, 
-and the other half is reserved for the \var{FreeMem} call stack.
-For example, the default value of 8 will cause eight levels of call frames
-to be dumped for the getmem call if \var{keepreleased} is \var{False}. If
-\var{KeepReleased} is true, then 4 levels of call frames will be dumped for
-the \var{GetMem} call and 4 frames wil be dumped for the \var{FreeMem} call.
-If you want to change this value, you must recode the \file{heaptrc} unit.
-
-\var{Quicktrace} determines whether the memory manager checks whether a 
-block that is about to be released is allocated correctly. This is a rather
-time consuming search, and slows program execution significantly, so by
-default it is set to \var{False}.
-
-If \var{HaltOnError} is set to \var{True} then an illegal call to 
-\var{FreeMem} will cause the memory manager to execute a \var{halt(1)} 
-instruction, causing a memory dump. By Default it is set to \var{True}.
-
-If \var{keepreleased} is set to true, then a list of freed memory 
-blocks is kept. This is useful if you suspect that the same memory block is
-released twice. However, this option is very memory intensive, so use it
-sparingly, and only when it's really necessary.
-
-If \var{add\_tail} is \var{True} (the default) then a check is also
-performed on the memory location just behind the allocated memory. 
-
-If \var{usecrc} is \var{True} (the default) then a crc check is performed
-on locations before and after the allocated memory. This is useful to
-detect memory overwrites.
-
-\section{Functions and procedures}
-
-\begin{procedure}{DumpHeap}
-\Declaration 
-procedure DumpHeap;
-\Description
-\var{DumpHeap} dumps to standard output a summary of memory usage.
-It is called automatically by the heaptrc unit when your program exits
-(by instaling an exit procedure), but it can be called at any time
-\Errors
-None.
-\SeeAlso
-\seep{MarkHeap}
-\end{procedure}
-
-\begin{procedure}{MarkHeap}
-\Declaration
-procedure MarkHeap;
-\Description
-\var{MarkHeap} marks all memory blocks with a special signature.
-You can use this if you think that you corruped the memory.
-\Errors
-None.
-\SeeAlso
-\seep{DumpHeap}
-\end{procedure}
-
-\begin{procedure}{SetExtraInfo}
-\Declaration
-procedure SetExtraInfo( size : longint;func : FillExtraInfoType);
-\Description
-You can use \var{SetExtraInfo} to store extra info in the blocks that
-the heaptrc unit reserves when tracing getmem calls. \var{Size} indicates the
-size (in bytes) that the trace mechanism should reserve for your extra
-information. For each call to \var{getmem}, \var{func} will be called,
-and passed a pointer to the memory reserved. 
-
-When dumping the memory summary, the extra info is shown as Longint values.
-
-\Errors
-You can only call \var{SetExtraInfo} if no memroy has been allocated
-yet. If memory was already allocated prior to the call to
-\var{SetExtraInfo}, then an error will be displayed on standard error
-output, and a \seep{DumpHeap} is executed.
-\SeeAlso
-\seep{DumpHeap},\seep{SetHeapTraceOutput}
-
-\end{procedure}
-
-\FPCexample{setinfo}
-
-\begin{procedure}{SetHeapTraceOutput}
-\Declaration
-Procedure SetHeapTraceOutput(const name : string);
-\Description
-\var{SetHeapTraceOutput} sets the filename into which heap trace info
-will be written. By default information is written to standard output,
-this function allows you to redirect the information to a file with 
-full filename \var{name}.
-\Errors
-If the file cannot be written to, errors will occur when writing the 
-trace.
-\SeeAlso
-\seep{SetExtraInfo}
-\end{procedure}
-
-%
-% $Log$
-% Revision 1.2  2003-03-16 15:22:18  peter
-%   * support for hevea
-%   * provided local copies or required styles since debian does not
-%     supply the listings.sty anymore
-%
-% Revision 1.1  2000/07/13 09:10:04  michael
-% + Initial import
-%
-% Revision 1.6  2000/07/11 18:07:26  peter
-%   * fixes for latex2html 0.99b2
-%
-% Revision 1.5  2000/05/16 21:07:55  michael
-% + Implemented large part of TODO list. Too much to denote
-%
-% Revision 1.4  2000/02/07 11:21:06  michael
-% + Documented heaptrc and lineinfo
-%
-% Revision 1.3  1999/06/25 22:12:16  michael
-% + Update to version 0.19 of listings package
-%
-% Revision 1.2  1998/12/15 23:50:52  michael
-% * Some updates
-%
-% Revision 1.1  1998/12/14 23:17:02  michael
-% + INitial implementation
-%

docs/ipc.tex

@@ -1,655 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1998, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA. 
-%
-\chapter{The IPC unit.}
-\label{ch:ipcunit}
-
-\FPCexampledir{ipcex}
-This chapter describes the IPC unit for Free Pascal. It was written for
-\linux by Micha\"el Van Canneyt. It gives all the functionality of system V 
-Inter-Process Communication: shared memory, semaphores and messages.
-It works only on the \linux operating system.
-
-The chapter is divided in 2 sections:
-\begin{itemize}
-\item The first section lists types, constants and variables from the
-interface part of the unit.
-\item The second section describes the functions defined in the unit.
-\end{itemize}
-\section {Types, Constants and variables : }
-\subsection{Variables}
-
-\begin{verbatim}
-Var
-  IPCerror : longint;
-\end{verbatim}
-The \var{IPCerror} variable is used to report errors, by all calls.
-\subsection{Constants}
-Many constants here are provided for completeness only, and should under
-normal circumstances not be used by the programmer.
-\begin{verbatim}
-Const 
-  IPC_CREAT  =  1 shl 9;  { create if key is nonexistent }
-  IPC_EXCL   =  2 shl 9;  { fail if key exists }
-  IPC_NOWAIT =  4 shl 9;  { return error on wait }
-\end{verbatim}
-These constants are used in the various \var{xxxget} calls.
-\begin{verbatim}
-  IPC_RMID = 0;     { remove resource }
-  IPC_SET  = 1;     { set ipc_perm options }
-  IPC_STAT = 2;     { get ipc_perm options }
-  IPC_INFO = 3;     { see ipcs }
-\end{verbatim}
-These constants can be passed to the various \var{xxxctl} calls.
-\begin{verbatim}
-const
-  MSG_NOERROR = 1 shl 12;
-  MSG_EXCEPT  = 2 shl 12;
-  MSGMNI = 128;
-  MSGMAX = 4056;
-  MSGMNB = 16384;
-\end{verbatim}
-These constants are used in the messaging system, they are not for use by
-the programmer.
-\begin{verbatim}
-const
-  SEM_UNDO = $1000;
-  GETPID = 11;
-  GETVAL = 12;
-  GETALL = 13;
-  GETNCNT = 14;
-  GETZCNT = 15;
-  SETVAL = 16;
-  SETALL = 17;
-\end{verbatim}
-These constants call be specified in the \seef{semop} call.
-\begin{verbatim}
-  SEMMNI = 128;
-  SEMMSL = 32;
-  SEMMNS = (SEMMNI * SEMMSL);
-  SEMOPM = 32;
-  SEMVMX = 32767;
-\end{verbatim}
-These constanst are used internally by the semaphore system, they should not
-be used by the programmer.
-\begin{verbatim}
-const
-  SHM_R      = 4 shl 6;
-  SHM_W      = 2 shl 6;
-  SHM_RDONLY = 1 shl 12;
-  SHM_RND    = 2 shl 12;
-  SHM_REMAP  = 4 shl 12;
-  SHM_LOCK   = 11;
-  SHM_UNLOCK = 12;
-\end{verbatim}
-These constants are used in the \seef{shmctl} call.
-
-\subsection{Types}
-The following two types are provided because they are needed. One they they
-should be defined in the system unit, however.
-\begin{verbatim}
-Type
-  PULong = ^Cardinal;
-  PWord  = ^Word;
-\end{verbatim}
-
-\begin{verbatim}
-Type 
-   TKey   = Longint;
-\end{verbatim}
-\var{TKey} is the type returned by the \seef{ftok} key generating function.
-\begin{verbatim}
-type
-  PIPC_Perm = ^TIPC_Perm;
-  TIPC_Perm = record
-    key : TKey;
-    uid, 
-    gid,
-    cuid,
-    cgid,
-    mode,
-    seq : Word;   
-  end;
-\end{verbatim}
-The \var{TIPC\_Perm} structure is used in all IPC systems to specify the
-permissions.
-\begin{verbatim}
-Type  
-  PSHMid_DS = ^TSHMid_ds; 
-  TSHMid_ds = record
-    shm_perm  : TIPC_Perm;
-    shm_segsz : longint;
-    shm_atime : longint;
-    shm_dtime : longint;
-    shm_ctime : longint;
-    shm_cpid  : word;
-    shm_lpid  : word;
-    shm_nattch : integer;
-    shm_npages : word;
-    shm_pages  : Pointer;
-    attaches   : pointer;
-  end;
-\end{verbatim}
-The \var{TSHMid\_ds} strucure is used in the \seef{shmctl} call to set or
-retrieve settings concerning shared memory.
-\begin{verbatim}
-type
-  PSHMinfo = ^TSHMinfo;
-  TSHMinfo = record
-    shmmax : longint;
-    shmmin : longint;
-    shmmni : longint;
-    shmseg : longint;
-    shmall : longint;
-  end;
-\end{verbatim}
-The \var{TSHMinfo} record is used by the shared memory system, and should
-not be accessed by the programer directly.
-\begin{verbatim}
-type
-  PMSG = ^TMSG;
-  TMSG = record
-    msg_next  : PMSG;
-    msg_type  : Longint;
-    msg_spot  : PChar;
-    msg_stime : Longint;
-    msg_ts    : Integer;
-  end;
-\end{verbatim}
-The \var{TMSG} record is used in the handling of message queues. There
-should be few cases where the programmer needs to access this data.
-\begin{verbatim}
-type
-  PMSQid_ds = ^TMSQid_ds;
-  TMSQid_ds = record
-    msg_perm   : TIPC_perm;
-    msg_first  : PMsg;
-    msg_last   : PMsg;
-    msg_stime  : Longint;
-    msg_rtime  : Longint;
-    msg_ctime  : Longint;
-    wwait      : Pointer;
-    rwait      : pointer;
-    msg_cbytes : word;
-    msg_qnum   : word;
-    msg_qbytes : word;
-    msg_lspid  : word;
-    msg_lrpid  : word;
-  end;
-\end{verbatim}
-The \var{TMSQid\_ds} record is returned by the \seef{msgctl} call, and
-contains all data about a message queue.
-\begin{verbatim}
-  PMSGbuf = ^TMSGbuf;
-  TMSGbuf = record
-    mtype : longint;
-    mtext : array[0..0] of char;
-  end;
-\end{verbatim}
-The \var{TMSGbuf} record is a record containing the data of a record. you
-should never use this record directly, instead you should make your own
-record that follows the structure of the \var{TMSGbuf} record, but that has
-a size that is big enough to accomodate your messages. The \var{mtype} field
-should always be present, and should always be filled.
-\begin{verbatim}
-Type
-  PMSGinfo = ^TMSGinfo;
-  TMSGinfo = record
-    msgpool : Longint;
-    msgmap  : Longint;
-    msgmax  : Longint;
-    msgmnb  : Longint;
-    msgmni  : Longint;
-    msgssz  : Longint;
-    msgtql  : Longint;
-    msgseg  : Word;
-  end;
-\end{verbatim}
-The  \var{TMSGinfo} record is used internally by the message queue system,
-and should not be used by the programmer directly.
-\begin{verbatim}
-Type
-  PSEMid_ds = ^PSEMid_ds;
-  TSEMid_ds = record
-    sem_perm : tipc_perm;
-    sem_otime : longint;
-    sem_ctime : longint;
-    sem_base         : pointer;
-    sem_pending      : pointer;
-    sem_pending_last : pointer;
-    undo             : pointer;
-    sem_nsems : word;
-  end;
-\end{verbatim}
-The \var{TSEMid\_ds} structure is returned by the \seef{semctl} call, and
-contains all data concerning a semahore.
-\begin{verbatim}
-Type
-  PSEMbuf = ^TSEMbuf;
-  TSEMbuf = record
-    sem_num : word;
-    sem_op  : integer;
-    sem_flg : integer;
-  end;
-\end{verbatim}
-The \var{TSEMbuf} record us use in the \seef{semop} call, and is used to
-specify which operations you want to do.
-\begin{verbatim}
-Type
-  PSEMinfo = ^TSEMinfo;
-  TSEMinfo = record
-    semmap : longint;
-    semmni : longint;
-    semmns : longint;
-    semmnu : longint;
-    semmsl : longint;
-    semopm : longint;
-    semume : longint;
-    semusz : longint;
-    semvmx : longint;
-    semaem : longint;
-  end;
-\end{verbatim}
-The \var{TSEMinfo} record is used internally by the semaphore system, and
-should not be used directly.
-\begin{verbatim}
-Type
-  PSEMun = ^TSEMun;
-  TSEMun = record
-   case longint of
-      0 : ( val : longint );
-      1 : ( buf : PSEMid_ds );
-      2 : ( arr : PWord );
-      3 : ( padbuf : PSeminfo );
-      4 : ( padpad : pointer );
-   end;
-\end{verbatim}
-The \var{TSEMun} variant record (actually a C union) is used in the
-\seef{semctl} call.
- 
-\section{Functions and procedures}
-
-\begin{function}{ftok}
-\Declaration
-Function ftok (Path : String; ID : char) : TKey;
-\Description
-\var{ftok} returns a key that can be used in a \seef{semget},\seef{shmget}
-or \seef{msgget} call to access a new or existing IPC resource.
-
-\var{Path} is the name of a file in the file system, \var{ID} is a
-character of your choice. The ftok call does the same as it's C couterpart,
-so a pascal program and a C program will access the same resource if
-they use the same \var{Path} and \var{ID}
-\Errors
-\var{ftok} returns -1 if the file in \var{Path} doesn't exist.
-\SeeAlso
-\seef{semget},\seef{shmget},\seef{msgget}
-\end{function}
-
-For an example, see \seef{msgctl}, \seef{semctl}, \seef{shmctl}.
-
-\begin{function}{msgget}
-\Declaration
-Function msgget(key: TKey; msgflg:longint):longint;	
-\Description
-\var{msgget} returns the ID of the message queue described by \var{key}.
-Depending on the flags in \var{msgflg}, a new queue is created.
-
-\var{msgflg} can have one or more of the following values (combined by ORs):
-\begin{description}
-\item[IPC\_CREAT] The queue is created if it doesn't already exist.
-\item[IPC\_EXCL] If used in combination with \var{IPC\_CREAT}, causes the
-call to fail if the queue already exists. It cannot be used by itself.
-\end{description}
-Optionally, the flags can be \var{OR}ed with a permission mode, which is the
-same mode that can be used in the file system.
-\Errors
-On error, -1 is returned, and \var{IPCError} is set.
-\SeeAlso
-\seef{ftok},\seef{msgsnd}, \seef{msgrcv}, \seef{msgctl}, \seem{semget}{2}
-\end{function}
-
-For an example, see \seef{msgctl}.
-
-\begin{function}{msgsnd}
-\Declaration
-Function msgsnd(msqid:longint; msgp: PMSGBuf; msgsz: longint; msgflg:longint): Boolean;
-\Description
-\var{msgsend} sends a message to a message queue with ID \var{msqid}.
-\var{msgp} is a pointer to a message buffer, that should be based on the
-\var{TMsgBuf} type. \var{msgsiz} is the size of the message (NOT of the
-message buffer record !)
-
-The \var{msgflg} can have a combination of the following values (ORed
-together):
-\begin{description}
-\item [0] No special meaning. The message will be written to the queue.
-If the queue is full, then the process is blocked.
-\item [IPC\_NOWAIT] If the queue is full, then no message is written,
-and the call returns immediatly.
-\end{description}
-
-The function returns \var{True} if the message was sent successfully, 
-\var{False} otherwise.
-\Errors
-In case of error, the call returns \var{False}, and \var{IPCerror} is set.
-\SeeAlso
-\seef{msgget}, \seef{msgrcv}, seef{msgctl}
-\end{function}
-
-For an example, see \seef{msgctl}.
-
-\begin{function}{msgrcv}
-\Declaration
-Function msgrcv(msqid:longint; msgp: PMSGBuf; msgsz: longint; msgtyp:longint; msgflg:longint): Boolean;
-\Description
-\var{msgrcv} retrieves a message of type \var{msgtyp} from the message 
-queue with ID \var{msqid}. \var{msgtyp} corresponds to the \var{mtype} 
-field of the \var{TMSGbuf} record. The message is stored in the \var{MSGbuf}
-structure pointed to by \var{msgp}.
-
-The \var{msgflg} parameter can be used to control the behaviour of the
-\var{msgrcv} call. It consists of an ORed combination of the following
-flags:
-\begin{description}
-\item [0] No special meaning.
-\item [IPC\_NOWAIT] if no messages are available, then the call returns
-immediatly, with the \var{ENOMSG} error.
-\item [MSG\_NOERROR] If the message size is wrong (too large), 
-no error is generated, instead the message is truncated. 
-Normally, in such cases, the call returns an error (E2BIG)
-\end{description}
-
-The function returns \var{True} if the message was received correctly,
-\var{False} otherwise.
-\Errors
-In case of error, \var{False} is returned, and \var{IPCerror} is set.
-\SeeAlso
-\seef{msgget}, \seef{msgsnd}, \seef{msgctl}
-\end{function}
-
-For an example, see \seef{msgctl}.
-
-\begin{function}{msgctl}
-\Declaration
-Function msgctl(msqid:longint; cmd: longint; buf: PMSQid\_ds): Boolean;
-\Description
-\var{msgctl} performs various operations on the message queue with id
-\var{ID}. Which operation is performed, depends on the \var{cmd} 
-parameter, which can have one of the following values:
-\begin{description}
-\item[IPC\_STAT] In this case, the \var{msgctl} call fills the
-\var{TMSQid\_ds} structure with information about the message queue.
-\item[IPC\_SET] in this case, the \var{msgctl} call sets the permissions
-of the queue as specified in the \var{ipc\_perm} record inside \var{buf}.
-\item[IPC\_RMID] If this is specified, the message queue will be removed 
-from the system.
-\end{description}
-
-\var{buf} contains the data that are needed by the call. It can be 
-\var{Nil} in case the message queue should be removed.
-
-The function returns \var{True} if successfull, \var{False} otherwise.
-\Errors
-On error, \var{False} is returned, and \var{IPCerror} is set accordingly.
-\SeeAlso
-\seef{msgget}, \seef{msgsnd}, \seef{msgrcv}
-\end{function}
-
-\FPCexample{msgtool}
-
-\begin{function}{semget}
-\Declaration
-Function semget(key:Tkey; nsems:longint; semflg:longint): longint;
-\Description
-\var{msgget} returns the ID of the semaphore set described by \var{key}.
-Depending on the flags in \var{semflg}, a new queue is created.
-
-\var{semflg} can have one or more of the following values (combined by ORs):
-\begin{description}
-\item[IPC\_CREAT] The queue is created if it doesn't already exist.
-\item[IPC\_EXCL] If used in combination with \var{IPC\_CREAT}, causes the
-call to fail if the set already exists. It cannot be used by itself.
-\end{description}
-Optionally, the flags can be \var{OR}ed with a permission mode, which is the
-same mode that can be used in the file system.
-
-if a new set of semaphores is created, then there will be \var{nsems}
-semaphores in it.
-\Errors
-On error, -1 is returned, and \var{IPCError} is set.
-\SeeAlso
-\seef{ftok}, \seef{semop}, \seef{semctl}
-\end{function}
-
-\begin{function}{semop}
-\Declaration
-Function semop(semid:longint; sops: pointer; nsops: cardinal): Boolean;
-\Description
-\var{semop} performs a set of operations on a message queue.
-\var{sops} points to an array of type \var{TSEMbuf}. The array should
-contain \var{nsops} elements.
-
-The fields of the \var{TSEMbuf} structure 
-\begin{verbatim}
-  TSEMbuf = record
-    sem_num : word;
-    sem_op  : integer;
-    sem_flg : integer;
-\end{verbatim}
-
-should be filled as follows:
-\begin{description}
-\item[sem\_num] The number of the semaphore in the set on which the
-operation must be performed.
-\item[sem\_op] The operation to be performed. The operation depends on the
-sign of \var{sem\_op}
-\begin{enumerate}
-\item A positive  number is simply added to the current value of the
-semaphore.
-\item If 0 (zero) is specified, then the process is suspended until the 
-  specified semaphore reaches zero.
-\item If a negative number is specified, it is substracted from the
-current value of the semaphore. If the value would become negative
-then the process is suspended until the value becomes big enough, unless
-\var{IPC\_NOWAIT} is specified in the \var{sem\_flg}.
-\end{enumerate}
-\item[sem\_flg] Optional flags: if \var{IPC\_NOWAIT} is specified, then the
-calling process will never be suspended.
-\end{description}
-
-The function returns \var{True} if the operations were successful,
-\var{False} otherwise.
-\Errors
-In case of error, \var{False} is returned, and \var{IPCerror} is set.
-\SeeAlso
-\seef{semget}, \seef{semctl}
-\end{function}
-
-\begin{function}{semctl}
-\Declaration
-Function semctl(semid:longint; semnum:longint; cmd:longint; var arg: tsemun): longint;
-\Description
-\var{semctl} performs various operations on the semaphore \var{semnum} w
-ith semaphore set id \var{ID}. 
-
-The \var{arg} parameter supplies the data needed for each call. This is
-a variant record that should be filled differently, according to the
-command:
-\begin{verbatim}
-Type
-  TSEMun = record
-   case longint of
-      0 : ( val : longint );
-      1 : ( buf : PSEMid_ds );
-      2 : ( arr : PWord );
-      3 : ( padbuf : PSeminfo );
-      4 : ( padpad : pointer );
-   end;
-\end{verbatim}
-
-
-Which operation is performed, depends on the \var{cmd} 
-parameter, which can have one of the following values:
-\begin{description}
-\item[IPC\_STAT] In this case, the arg record should have it's \var{buf}
-field set to the address of a \var{TSEMid\_ds} record. 
-The \var{semctl} call fills this \var{TSEMid\_ds} structure with information 
-about the semaphore set. 
-\item[IPC\_SET] In this case, the \var{arg} record should have it's \var{buf}
-field set to the address of a \var{TSEMid\_ds} record.
-The \var{semctl} call sets the permissions of the queue as specified in 
-the \var{ipc\_perm} record.
-\item[IPC\_RMID] If this is specified, the semaphore set is removed from 
-from the system.
-\item[GETALL] In this case, the \var{arr} field of \var{arg} should point
-to a memory area where the values of the semaphores will be stored.
-The size of this memory area is \var{SizeOf(Word)* Number of semaphores
-in the set}.
-This call will then fill the memory array with all the values of the
-semaphores.
-\item[GETNCNT] This will fill the \var{val} field of the \var{arg} union
-with the bumber of processes waiting for resources.
-\item[GETPID] \var{semctl} returns the process ID of the process that
-performed the last \seef{semop} call.
-\item[GETVAL] \var{semctl} returns the value of the semaphore with number
-\var{semnum}.
-\item[GETZCNT] \var{semctl} returns the number of processes waiting for 
-semaphores that reach value zero.
-\item[SETALL] In this case, the \var{arr} field of \var{arg} should point
-to a memory area where the values of the semaphores will be retrieved from.
-The size of this memory area is \var{SizeOf(Word)* Number of semaphores
-in the set}.
-This call will then set the values of the semaphores from the memory array.
-\item[SETVAL] This will set the value of semaphore \var{semnum} to the value
-in the \var{val} field of the \var{arg} parameter.
-\end{description}
-
-The function returns -1 on error.
-\Errors
-The function returns -1 on error, and \var{IPCerror} is set accordingly.
-\SeeAlso
-\seef{semget}, \seef{semop}
-\end{function}
-
-\FPCexample{semtool}
-
-\begin{function}{shmget}
-\Declaration
-Function shmget(key: Tkey; Size:longint; flag:longint):longint;
-\Description
-\var{shmget} returns the ID of a shared memory block, described by \var{key}.
-Depending on the flags in \var{flag}, a new memory block is created.
-
-\var{flag} can have one or more of the following values (combined by ORs):
-\begin{description}
-\item[IPC\_CREAT] The queue is created if it doesn't already exist.
-\item[IPC\_EXCL] If used in combination with \var{IPC\_CREAT}, causes the
-call to fail if the queue already exists. It cannot be used by itself.
-\end{description}
-Optionally, the flags can be \var{OR}ed with a permission mode, which is the
-same mode that can be used in the file system.
-
-if a new memory block is created, then it will have size \var{Size}
-semaphores in it.
-\Errors
-On error, -1 is returned, and \var{IPCError} is set.
-\SeeAlso
-\end{function}
-
-\begin{function}{shmat}
-\Declaration
-Function shmat (shmid:longint; shmaddr:pchar; shmflg:longint):pchar;
-\Description
-\var{shmat} attaches a shared memory block with identified \var{shmid} 
-to the current process. The function returns a pointer to the shared memory
-block.
-
-If \var{shmaddr} is \var{Nil}, then the system chooses a free unmapped
-memory region, as high up in memory space as possible.
-
-If \var{shmaddr} is non-nil, and \var{SHM\_RND} is in \var{shmflg}, then 
-the returned address is \var{shmaddr}, rounded down to \var{SHMLBA}.
-If \var{SHM\_RND} is not specified, then \var{shmaddr} must be a
-page-aligned address.
-
-The parameter \var{shmflg} can be used to control the behaviour of the
-\var{shmat} call. It consists of a ORed combination of the following
-costants:
-\begin{description}
-\item[SHM\_RND] The suggested address in \var{shmaddr} is rounded down to
-\var{SHMLBA}.
-\item[SHM\_RDONLY] the shared memory is attached for read access only.
-Otherwise the memory is attached for read-write. The process then needs
-read-write permissions to access the shared memory.
-\end{description}
-\Errors
-If an error occurs, -1 is returned, and \var{IPCerror} is set.
-\SeeAlso
-\seef{shmget}, \seef{shmdt}, \seef{shmctl}
-\end{function}
-
-For an example, see \seef{shmctl}.
-
-\begin{function}{shmdt}
-\Declaration
-Function shmdt (shmaddr:pchar):boolean;
-\Description
-\var{shmdt} detaches the shared memory at address \var{shmaddr}. This shared
-memory block is unavailable to the current process, until it is attached
-again by a call to \seef{shmat}.
-
-The function returns \var{True} if the memory block was detached
-successfully, \var{False} otherwise.
-\Errors
-On error, False is returned, and IPCerror is set.
-\SeeAlso
-\seef{shmget}, \seef{shmat}, \seef{shmctl}
-\end{function}
-
-\begin{function}{shmctl}
-\Declaration
-Function shmctl(shmid:longint; cmd:longint; buf: pshmid\_ds): Boolean;
-\Description
-\var{shmctl} performs various operations on the shared memory block
-identified by identifier \var{shmid}.
-
-The \var{buf} parameter points to a \var{TSHMid\_ds} record. The 
-\var{cmd} parameter is used to pass which operation is to be performed.
-It can have one of the following values :
-\begin{description}
-\item[IPC\_STAT] \var{shmctl} fills the \var{TSHMid\_ds} record that 
-\var{buf} points to with the available information about the shared memory
-block.
-\item[IPC\_SET] applies the values in the \var{ipc\_perm} record that
-\var{buf} points to, to the shared memory block.
-\item[IPC\_RMID] the shared memory block is destroyed (after all processes
-to which the block is attached, have detached from it).
-\end{description}
-
-If successful, the function returns \var{True}, \var{False} otherwise.
-\Errors
-If an error occurs, the function returns \var{False}, and \var{IPCerror}
-is set.
-\SeeAlso
-\seef{shmget}, \seef{shmat}, \seef{shmdt}
-\end{function}
-
-\FPCexample{shmtool}

docs/keyboard.tex

@@ -1,629 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 2001, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA.
-%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% The Keyboard unit
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\chapter{The KEYBOARD unit}
-\FPCexampledir{kbdex}
-
-The \file{KeyBoard} unit implements a keyboard access layer which is system
-independent. It can be used to poll the keyboard state and wait for certain
-events. Waiting for a keyboard event can be done with the \seef{GetKeyEvent}
-function, which will return a driver-dependent key event. This key event can
-be translated to a interpretable event by the \seef{TranslateKeyEvent}
-function. The result of this function can be used in the other event
-examining functions.
-
-A custom keyboard driver can be installed using the \seef{SetKeyboardDriver}
-function. The current keyboard driver can be retrieved using the
-\seep{GetKeyboardDriver} function. The last section of this chapter
-demonstrates how to make a keyboard driver.
-
-\section{Constants, Type and variables }
-
-\subsection{Constants}
-
-The following constants define some error constants, which may be returned
-by the keyboard functions.
-\begin{verbatim}
-errKbdBase           = 1010;
-errKbdInitError      = errKbdBase + 0;
-errKbdNotImplemented = errKbdBase + 1;
-\end{verbatim}
-The following constants denote special keyboard keys. The first constants
-denote the function keys:
-\begin{verbatim}
-const
-  kbdF1        = $FF01;
-  kbdF2        = $FF02;
-  kbdF3        = $FF03;
-  kbdF4        = $FF04;
-  kbdF5        = $FF05;
-  kbdF6        = $FF06;
-  kbdF7        = $FF07;
-  kbdF8        = $FF08;
-  kbdF9        = $FF09;
-  kbdF10       = $FF0A;
-  kbdF11       = $FF0B;
-  kbdF12       = $FF0C;
-  kbdF13       = $FF0D;
-  kbdF14       = $FF0E;
-  kbdF15       = $FF0F;
-  kbdF16       = $FF10;
-  kbdF17       = $FF11;
-  kbdF18       = $FF12;
-  kbdF19       = $FF13;
-  kbdF20       = $FF14;
-\end{verbatim}
-Constants  \$15 till \$1F are reserved for future function keys. The
-following constants denote the cursor movement keys:
-\begin{verbatim}
-  kbdHome      = $FF20;
-  kbdUp        = $FF21;
-  kbdPgUp      = $FF22;
-  kbdLeft      = $FF23;
-  kbdMiddle    = $FF24;
-  kbdRight     = $FF25;
-  kbdEnd       = $FF26;
-  kbdDown      = $FF27;
-  kbdPgDn      = $FF28;
-
-  kbdInsert    = $FF29;
-  kbdDelete    = $FF2A;
-\end{verbatim}
-Constants \$2B till \$2F are reserved for future keypad keys.
-The following flags are also defined:
-\begin{verbatim}
-  kbASCII       = $00;
-  kbUniCode     = $01;
-  kbFnKey       = $02;
-  kbPhys        = $03;
-  kbReleased    = $04;
-\end{verbatim}
-They can be used to check what kind of data a key event contains.
-The following shift-state flags can be used to determine the shift state of
-a key (i.e. which of the SHIFT, ALT and CTRL keys were pressed
-simultaneously with a key):
-\begin{verbatim}
-  kbLeftShift   = 1;
-  kbRightShift  = 2;
-  kbShift       = kbLeftShift or kbRightShift;
-  kbCtrl        = 4;
-  kbAlt         = 8;
-\end{verbatim}
-The following constant strings are used in the key name functions 
-\seef{FunctionKeyName} and \seef{KeyEventToString}:
-\begin{verbatim}
-SShift       : Array [1..3] of string[5] = ('SHIFT','CTRL','ALT');
-LeftRight   : Array [1..2] of string[5] = ('LEFT','RIGHT');
-UnicodeChar : String = 'Unicode character ';
-SScanCode    : String = 'Key with scancode ';
-SUnknownFunctionKey : String = 'Unknown function key : ';
-SAnd         : String = 'AND';
-SKeyPad      : Array [0..($FF2F-kbdHome)] of string[6] = 
-               ('Home','Up','PgUp','Left',
-                'Middle','Right','End','Down',
-                'PgDn','Insert','Delete','',
-                '','','','');
-\end{verbatim}
-They can be changed to localize the key names when needed.
-
-\subsection{Types}
-The \var{TKeyEvent} type is the base type for all keyboard events:
-\begin{verbatim}
-  TKeyEvent = Longint;
-\end{verbatim}
-The key stroke is encoded in the 4 bytes of the \var{TKeyEvent} type. 
-The various fields of the key stroke encoding can be obtained by typecasting
-the \var{TKeyEvent} type to the \var{TKeyRecord} type:
-\begin{verbatim}
-  TKeyRecord = packed record
-    KeyCode : Word;
-    ShiftState, Flags : Byte;
-  end;
-\end{verbatim}
-The structure of a \var{TKeyRecord} structure is explained in \seet{keyevent}.
-\begin{FPCltable}{lp{10cm}}{Structure of TKeyRecord}{keyevent}
-Field & Meaning \\ \hline
-KeyCode & Depending on \var{flags} either the physical representation of a key
-         (under DOS scancode, ascii code pair), or the translated
-           ASCII/unicode character.\\
-ShiftState & Shift-state when this key was pressed (or shortly after) \\
-Flags & Determine how to interpret \var{KeyCode} \\ \hline
-\end{FPCltable}
-The shift-state can be checked using the various shift-state constants, 
-and the flags in the last byte can be checked using one of the
-kbASCII, kbUniCode, kbFnKey, kbPhys, kbReleased constants.
-
-If there are two keys returning the same char-code, there's no way to find
-out which one was pressed (Gray+ and Simple+). If it needs to be known which
-was pressed, the untranslated keycodes must be used, but these are system
-dependent. System dependent constants may be defined to cover those, with
-possibily having the same name (but different value).
-
-The \var{TKeyboardDriver} record can be used to install a custom keyboard
-driver with the \seef{SetKeyboardDriver} function:
-\begin{verbatim}
-Type 
-  TKeyboardDriver = Record
-    InitDriver : Procedure;
-    DoneDriver : Procedure;
-    GetKeyEvent : Function : TKeyEvent;
-    PollKeyEvent : Function : TKeyEvent;
-    GetShiftState : Function : Byte;
-    TranslateKeyEvent : Function (KeyEvent: TKeyEvent): TKeyEvent;
-    TranslateKeyEventUniCode: Function (KeyEvent: TKeyEvent): TKeyEvent;
-  end;
-\end{verbatim}
-The various fields correspond to the different functions of the keyboard unit 
-interface. For more information about this record see \sees{kbddriver}
-
-\section{Functions and Procedures}
-
-\begin{procedure}{DoneKeyboard}
-\Declaration
-Procedure DoneKeyboard;
-\Description
-\var{DoneKeyboard} de-initializes the keyboard interface if the keyboard
-driver is active. If the keyboard driver is not active, the function does
-nothing.
-
-This will cause the keyboard driver to clear up any allocated memory, 
-or restores the console or terminal the program was running in to its 
-initial state before the call to \seep{InitKeyBoard}. This function should 
-be called on program exit. Failing to do so may leave the terminal or
-console window in an unusable state. Its exact action depends on the 
-platform on which the program is running.
-\Errors
-None.
-\SeeAlso
-\seep{InitKeyBoard}
-\end{procedure}
-
-For an example, see most other functions.
-
-\begin{function}{FunctionKeyName}
-\Declaration
-Function FunctionKeyName (KeyCode : Word) : String;
-\Description
-\var{FunctionKeyName} returns a string representation of the function key
-with code \var{KeyCode}. This can be an actual function key, or one of the
-cursor movement keys.
-\Errors
-In case \var{KeyCode} does not contain a function code, the
-\var{SUnknownFunctionKey} string is returned, appended with the
-\var{KeyCode}.
-\SeeAlso
-\seef{ShiftStateToString}
-\seef{KeyEventToString}
-\end{function}
-
-\FPCexample{ex8}
-
-\begin{procedure}{GetKeyboardDriver}
-\Declaration
-Procedure GetKeyboardDriver (Var Driver : TKeyboardDriver);
-\Description
-\var{GetKeyBoardDriver} returns in \var{Driver} the currently active
-keyboard driver. This function can be used to enhance an existing
-keyboarddriver.
-
-For more information on getting and setting the keyboard driver
-\sees{kbddriver}.
-\Errors
-None.
-\SeeAlso
-\seef{SetKeyboardDriver}
-\end{procedure}
-
-\begin{function}{GetKeyEvent}
-\Declaration
-function GetKeyEvent: TKeyEvent;
-\Description
-\var{GetKeyEvent} returns the last keyevent if one was stored in
-\var{PendingKeyEvent}, or waits for one if none is available.
-A non-blocking version is available in \seef{PollKeyEvent}.
-
-The returned key is encoded as a \var{TKeyEvent} type variable, and
-is normally the physical key scan code, (the scan code is driver 
-dependent) which can be translated with one of the translation 
-functions \seef{TranslateKeyEvent} or \seef{TranslateKeyEventUniCode}. 
-See the types section for a description of how the key is described.
-\Errors
-If no key became available, 0 is returned.
-\SeeAlso
-\seep{PutKeyEvent}, \seef{PollKeyEvent}, \seef{TranslateKeyEvent},
-\seef{TranslateKeyEventUniCode}
-\end{function}
-
-\FPCexample{ex1}
-
-\begin{function}{GetKeyEventChar}
-\Declaration
-function GetKeyEventChar(KeyEvent: TKeyEvent): Char;
-\Description
-\var{GetKeyEventChar} returns the charcode part of the given 
-\var{KeyEvent}, if it contains a translated character key 
-keycode. The charcode is simply the ascii code of the 
-character key that was pressed.
-
-It returns the null character if the key was not a character key, but e.g. a
-function key.
-\Errors
-None.
-\SeeAlso
-\seef{GetKeyEventUniCode},
-\seef{GetKeyEventShiftState}, 
-\seef{GetKeyEventFlags},
-\seef{GetKeyEventCode},
-\seef{GetKeyEvent}
-\end{function}
-
-For an example, see \seef{GetKeyEvent}
-
-\begin{function}{GetKeyEventCode}
-\Declaration
-function GetKeyEventCode(KeyEvent: TKeyEvent): Word;
-\Description
-\var{GetKeyEventCode} returns the translated function keycode part of 
-the given KeyEvent, if it contains a translated function key.
-
-If the key pressed was not a function key, the null character is returned.
-\Errors
-None.
-\SeeAlso
-\seef{GetKeyEventUniCode},
-\seef{GetKeyEventShiftState}, 
-\seef{GetKeyEventFlags},
-\seef{GetKeyEventChar},
-\seef{GetKeyEvent}
-\end{function}
-
-\FPCexample{ex2}
-
-\begin{function}{GetKeyEventFlags}
-\Declaration
-function GetKeyEventFlags(KeyEvent: TKeyEvent): Byte;
-\Description
-\var{GetKeyEventFlags} returns the flags part of the given 
-\var{KeyEvent}. 
-\Errors
-None.
-\SeeAlso
-\seef{GetKeyEventUniCode},
-\seef{GetKeyEventShiftState}, 
-\seef{GetKeyEventCode},
-\seef{GetKeyEventChar},
-\seef{GetKeyEvent}
-\end{function}
-
-For an example, see \seef{GetKeyEvent}
-
-\begin{function}{GetKeyEventShiftState}
-\Declaration
-function GetKeyEventShiftState(KeyEvent: TKeyEvent): Byte;
-\Description
-\var{GetKeyEventShiftState} returns the shift-state values of 
-the given \var{KeyEvent}. This can be used to detect which of the modifier
-keys \var{Shift}, \var{Alt} or \var{Ctrl} were pressed. If none were
-pressed, zero is returned.
-
-Note that this function does not always return expected results;
-In a unix X-Term, the modifier keys do not always work.
-\Errors
-None.
-\SeeAlso
-\seef{GetKeyEventUniCode},
-\seef{GetKeyEventFlags}, 
-\seef{GetKeyEventCode},
-\seef{GetKeyEventChar},
-\seef{GetKeyEvent}
-\end{function}
-
-\FPCexample{ex3}
-
-\begin{function}{GetKeyEventUniCode}
-\Declaration
-function GetKeyEventUniCode(KeyEvent: TKeyEvent): Word;
-\Description
-\var{GetKeyEventUniCode} returns the unicode part of the 
-given \var{KeyEvent} if it contains a translated unicode 
-character.
-\Errors
-None.
-\SeeAlso
-\seef{GetKeyEventShiftState},
-\seef{GetKeyEventFlags}, 
-\seef{GetKeyEventCode},
-\seef{GetKeyEventChar},
-\seef{GetKeyEvent}
-\end{function}
-
-No example available yet.
-
-\begin{procedure}{InitKeyBoard}
-\Declaration
-procedure InitKeyboard;
-\Description
-\var{InitKeyboard} initializes the keyboard driver. 
-If the driver is already active, it does nothing. When the driver is
-initialized, it will do everything necessary to ensure the functioning of
-the keyboard, including allocating memory, initializing the terminal etc.
-
-This function should be called once, before using any of the
-keyboard functions. When it is called, the \seep{DoneKeyboard} function
-should also be called before exiting the program or changing the keyboard
-driver with \seef{SetKeyboardDriver}.
-\Errors
-None.
-\SeeAlso
-\seep{DoneKeyboard}, \seef{SetKeyboardDriver}
-\end{procedure}
-
-For an example, see most other functions.
-
-\begin{function}{IsFunctionKey}
-\Declaration
-function IsFunctionKey(KeyEvent: TKeyEvent): Boolean;
-\Description
-\var{IsFunctionKey} returns \var{True} if the given key event
-in \var{KeyEvent} was a function key or not.
-\Errors
-None.
-\SeeAlso
-\seef{GetKeyEvent}
-\end{function}
-
-\FPCexample{ex7}
-
-\begin{function}{KeyEventToString}
-\Declaration
-Function KeyEventToString(KeyEvent : TKeyEvent) : String;
-\Description
-\var{KeyEventToString} translates the key event in \var{KeyEvent} to a
-human-readable description of the pressed key. It will use the constants
-described in the constants section to do so.
-\Errors
-If an unknown key is passed, the scancode is returned, prefixed with the 
-\var{SScanCode} string.
-\SeeAlso
-\seef{FunctionKeyName}, \seef{ShiftStateToString}
-\end{function}
-
-For an example, see most other functions.
-
-\begin{function}{PollKeyEvent}
-\Declaration
-function PollKeyEvent: TKeyEvent;
-\Description
-\var{PollKeyEvent} checks whether a key event is available, 
-and returns it if one is found. If no event is pending, 
-it returns 0. 
-
-Note that this does not remove the key from the pending keys. 
-The key should still be retrieved from the pending key events 
-list with the \seef{GetKeyEvent} function.
-\Errors
-None.
-\SeeAlso
-\seep{PutKeyEvent}, \seef{GetKeyEvent}
-\end{function}
-
-\FPCexample{ex4}
-
-\begin{function}{PollShiftStateEvent}
-\Declaration
-function PollShiftStateEvent: TKeyEvent;
-\Description
-\var{PollShiftStateEvent} returns the current shiftstate in a 
-keyevent. This will return 0 if there is no key event pending.
-\Errors
-None.
-\SeeAlso
-\seef{PollKeyEvent}, \seef{GetKeyEvent}
-\end{function}
-
-\FPCexample{ex6}
-
-\begin{procedure}{PutKeyEvent}
-\Declaration
-procedure PutKeyEvent(KeyEvent: TKeyEvent);
-\Description
-\var{PutKeyEvent} adds the given \var{KeyEvent} to the input 
-queue. Please note that depending on the implementation this 
-can hold only one value, i.e. when calling \var{PutKeyEvent}
-multiple times, only the last pushed key will be remembered.
-\Errors
-None
-\SeeAlso
-\seef{PollKeyEvent}, \seef{GetKeyEvent}
-\end{procedure}
-
-\FPCexample{ex5}
-
-\begin{function}{SetKeyboardDriver}
-\Declaration
-Function SetKeyboardDriver (Const Driver : TKeyboardDriver) : Boolean;
-\Description
-\var{SetKeyBoardDriver} sets the keyboard driver to \var{Driver}, if the
-current keyboard driver is not yet initialized. If the current
-keyboard driver is initialized, then \var{SetKeyboardDriver} does 
-nothing. Before setting the driver, the currently active driver should
-be disabled with a call to \seep{DoneKeyboard}.
-
-The function returns \var{True} if the driver was set, \var{False} if not.
-
-For more information on setting the keyboard driver, see \sees{kbddriver}.
-\Errors
-None.
-\SeeAlso
-\seep{GetKeyboardDriver}, \seep{DoneKeyboard}.
-\end{function}
-
-\begin{function}{ShiftStateToString}
-\Declaration
-Function ShiftStateToString(KeyEvent : TKeyEvent; UseLeftRight : Boolean) : String;
-\Description
-\var{ShiftStateToString} returns a string description of the shift state
-of the key event \var{KeyEvent}. This can be an empty string. 
-
-The shift state is described using the strings in the \var{SShift} constant.
-\Errors
-None.
-\SeeAlso
-\seef{FunctionKeyName}, \seef{KeyEventToString}
-\end{function}
-
-For an example, see \seef{PollShiftStateEvent}.
-
-\begin{function}{TranslateKeyEvent}
-\Declaration
-function TranslateKeyEvent(KeyEvent: TKeyEvent): TKeyEvent;
-\Description
-\var{TranslateKeyEvent} performs ASCII translation of the \var{KeyEvent}.
-It translates a physical key to a function key if the key is a function key,
-and translates the physical key to the ordinal of the ascii character if 
-there is an equivalent character key.
-\Errors
-None.
-\SeeAlso
-\seef{TranslateKeyEventUniCode}
-\end{function}
-
-For an example, see \seef{GetKeyEvent}
-
-\begin{function}{TranslateKeyEventUniCode}
-\Declaration
-function TranslateKeyEventUniCode(KeyEvent: TKeyEvent): TKeyEvent;
-\Description
-\var{TranslateKeyEventUniCode} performs Unicode translation of the 
-\var{KeyEvent}. It is not yet implemented for all platforms.
-
-\Errors
-If the function is not yet implemented, then the \var{ErrorCode} of the 
-\file{system} unit will be set to \var{errKbdNotImplemented}
-\SeeAlso
-\end{function}
-
-No example available yet.
-
-\section{Keyboard scan codes}
-Special physical keys are encoded with the DOS scan codes for these keys
-in the second byte of the \var{TKeyEvent} type.
-A complete list of scan codes can be found in \seet{keyscans}. This is the
-list of keys that is used by the default key event translation mechanism.
-When writing a keyboard driver, either these constants should be returned
-by the various key event functions, or the \var{TranslateKeyEvent} hook
-should be implemented by the driver.
-\begin{FPCltable}{llllll}{Physical keys scan codes}{keyscans}
-Code & Key & Code & Key & Code & Key\\ \hline
-\input{keys.tex}
-\end{FPCltable}
-A list of scan codes for special keys and combinations with the SHIFT, ALT
-and CTRL keys can be found in \seet{speckeys}; They are for quick reference
-only.
-\begin{FPCltable}{llccc}{Special keys scan codes}{speckeys}
-Key         & Code  & SHIFT-Key & CTRL-Key & Alt-Key \\ \hline
-NoKey       &  00   &       &     &     \\
-F1          &  3B   &  54   & 5E  & 68  \\
-F2          &  3C   &  55   & 5F  & 69  \\
-F3          &  3D   &  56   & 60  & 6A  \\
-F4          &  3E   &  57   & 61  & 6B  \\
-F5          &  3F   &  58   & 62  & 6C  \\
-F6          &  40   &  59   & 63  & 6D  \\
-F7          &  41   &  5A   & 64  & 6E  \\
-F8          &  42   &  5A   & 65  & 6F  \\
-F9          &  43   &  5B   & 66  & 70  \\
-F10         &  44   &  5C   & 67  & 71  \\
-F11         &  85   &  87   & 89  & 8B  \\
-F12         &  86   &  88   & 8A  & 8C  \\
-Home        &  47   &       & 77  & 97  \\ 
-Up          &  48   &       & 8D  & 98  \\
-PgUp        &  49   &       & 84  & 99  \\
-Left        &  4B   &       & 73  & 9B  \\
-Center      &  4C   &       & 8F  &     \\
-Right       &  4D   &       & 74  & 9D  \\
-end         &  4F   &       & 75  & 9F  \\
-Down        &  50   &       & 91  & A0  \\
-PgDn        &  51   &       & 76  & A1  \\
-Ins         &  52   & 05    & 04  & A2  \\
-Del         &  53   & 07    & 06  & A3  \\
-Tab         &  8    & 0F    & 94  & A5  \\
-GreyPlus    &       &       & 90  & 4E  \\
-\hline
-\end{FPCltable}
-\section{Writing a keyboard driver}
-\label{se:kbddriver}
-Writing a keyboard driver means that hooks must be created for most of the 
-keyboard unit functions. The \var{TKeyBoardDriver} record contains a field
-for each of the possible hooks:
-\begin{verbatim}
-TKeyboardDriver = Record
-  InitDriver : Procedure;
-  DoneDriver : Procedure;
-  GetKeyEvent : Function : TKeyEvent;
-  PollKeyEvent : Function : TKeyEvent;
-  GetShiftState : Function : Byte;
-  TranslateKeyEvent : Function (KeyEvent: TKeyEvent): TKeyEvent;
-  TranslateKeyEventUniCode: Function (KeyEvent: TKeyEvent): TKeyEvent;
-end;
-\end{verbatim}
-The meaning of these hooks is explained below:
-\begin{description}
-\item[InitDriver] Called to initialize and enable the driver. 
-Guaranteed to be called only once. This should initialize all needed things
-for the driver.
-\item[DoneDriver] Called to disable and clean up the driver. Guaranteed to be
-called after a call to \var{initDriver}. This should clean up all
-things initialized by \var{InitDriver}.
-\item[GetKeyEvent] Called by \seef{GetKeyEvent}. Must wait for and return the
-next key event. It should NOT store keys.
-\item[PollKeyEvent] Called by \seef{PollKeyEvent}. It must return the next key
-event if there is one. Should not store keys. 
-\item[GetShiftState] Called by \seef{PollShiftStateEvent}.  Must return the current
-shift state.
-\item[TranslateKeyEvent] Should translate a raw key event to a cOrrect
-key event, i.e. should fill in the shiftstate and convert function key
-scancodes to function key keycodes. If the
-\var{TranslateKeyEvent} is not filled in, a default translation function
-will be called which converts the known scancodes from the tables in the
-previous section to a correct keyevent.
-\item[TranslateKeyEventUniCode] Should translate a key event to a unicode key
-representation. 
-\end{description}
-Strictly speaking, only the \var{GetKeyEvent} and \var{PollKeyEvent}
-hooks must be implemented for the driver to function correctly. 
-
-The following unit demonstrates how a keyboard driver can be installed.
-It takes the installed driver, and hooks into the \var{GetKeyEvent}
-function to register and log the key events in a file. This driver
-can work on top of any other driver, as long as it is inserted in the 
-\var{uses} clause {\em after} the real driver unit, and the real driver unit
-should set the driver record in its initialization section.
-\FPCexample{logkeys}
-The following program demonstrates the use of the unit:
-\FPCexample{ex9}
-Note that with a simple extension of this unit could be used to make a
-driver that is capable of recording and storing a set of keyboard strokes,
-and replaying them at a later time, so a 'keyboard macro' capable driver.
-This driver could sit on top of any other driver.

docs/linux.tex

@@ -1,3541 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1997, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA. 
-%
-\chapter{The LINUX unit.}
-\label{ch:linux}
-
-\FPCexampledir{linuxex}
-This chapter describes the LINUX unit for Free Pascal. The unit was written
-by Micha\"el van Canneyt. It works only on the Linux operating system.
-This chapter is divided in 3 sections:
-\begin{itemize}
-\item The first section lists all constants, types and variables, as listed
-in the interface section of the LINUX unit.
-\item The second section gives and overview of all available functions,
-grouped by category.
-\item The third section describes all procedures and functions in the LINUX
-unit.
-\end{itemize}
-
-% Type, Variable and Constant declarations
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Type, Variable and Constant declarations}
-
-%
-\subsection{Types}
-\label{sec:types}
-PGlob and TGlob are 2 types used in the \seef{Glob} function:
-\begin{verbatim}
-PGlob = ^TGlob;
-TGlob = record
-  Name : PChar;
-  Next : PGlob;
-  end;
-\end{verbatim}
-The following types are used in the signal-processing procedures.
-\begin{verbatim}
-tfpreg = record
-  significand: array[0..3] of word;
-  exponent: word;
-end;
-
-pfpstate = ^tfpstate;
-tfpstate = record
-  cw, sw, tag, ipoff, cssel, dataoff, datasel: cardinal;
-  st: array[0..7] of tfpreg;                            
-  status: cardinal;
-end;
-
-PSigContextRec = ^SigContextRec;
-SigContextRec = record
-  gs, __gsh: word;
-  fs, __fsh: word;
-  es, __esh: word;
-  ds, __dsh: word;
-  edi: cardinal;   
-  esi: cardinal;   
-  ebp: cardinal;   
-  esp: cardinal;   
-  ebx: cardinal;   
-  edx: cardinal;   
-  ecx: cardinal;   
-  eax: cardinal;   
-  trapno: cardinal;
-  err: cardinal;   
-  eip: cardinal;   
-  cs, __csh: word; 
-  eflags: cardinal;
-  esp_at_signal: cardinal;
-  ss, __ssh: word;
-  fpstate: pfpstate;
-  oldmask: cardinal;
-  cr2: cardinal;
-  end;
-\end{verbatim}
-The above records contain information about the processor state and process
-state at the moment a signal is sent to your program.
-
-The records below are used in catching signals.
-\begin{verbatim}
-TSigAction = procedure(Sig: Longint; SigContext: SigContextRec);cdecl;
-SignalHandler   = Procedure ( Sig : Integer);cdecl;
-
-PSignalHandler  = SignalHandler;
-SignalRestorer  = Procedure;cdecl;
-PSignalrestorer = SignalRestorer;
-SigActionRec = packed record
-  Handler  : record
-    case byte of   
-      0: (Sh: SignalHandler);
-      1: (Sa: TSigAction);   
-    end;
-  Sa_Mask     : SigSet;
-  Sa_Flags    : Longint;
-  Sa_restorer : SignalRestorer; { Obsolete - Don't use }
-end;
-  PSigActionRec = ^SigActionRec;
-\end{verbatim}
-Stat is used to store information about a file. It is defined in the
-syscalls unit.
-\begin{verbatim}
-  stat = record
-     dev    : word;
-     pad1   : word;
-     ino    : longint;
-     mode   : word;
-     nlink  : word;
-     uid    : word;
-     gid    : word;
-     rdev   : word;
-     pad2   : word;
-     size   : longint;
-     blksze : Longint;
-     blocks : Longint;
-     atime  : Longint;
-     unused1 : longint;
-     mtime   : Longint;
-     unused2 : longint;
-     ctime   : Longint;
-     unused3 : longint;
-     unused4 : longint;
-     unused5 : longint;
-     end;
- \end{verbatim}
-Statfs is used to store information about a filesystem. It is defined in
-the syscalls unit.
-\begin{verbatim}
-   statfs = record
-     fstype   : longint;
-     bsize    : longint;
-     blocks   : longint;
-     bfree    : longint;
-     bavail   : longint;
-     files    : longint;
-     ffree    : longint;
-     fsid     : longint;
-     namelen  : longint; 
-     spare    : array [0..6] of longint;
-     end
-\end{verbatim}
-\var{Dir and PDir} are used in the \seef{OpenDir} and \seef{ReadDir}
-functions. 
-\begin{verbatim}
-  TDir =record
-    fd     : integer;
-    loc    : longint;
-    size   : integer;
-    buf    : pdirent;
-    nextoff: longint;
-    dd_max : integer; 
-    lock   : pointer;
-  end;
-  PDir =^TDir;
-\end{verbatim}
-\var{Dirent, PDirent} are used in the \seef{ReadDir} function to return files in a directory.
-\begin{verbatim}
- PDirent = ^Dirent;
- Dirent = Record  
-   ino,
-   off    : longint;
-   reclen : word;
-   name   : string[255]
- end; 
-\end{verbatim}
-Termio and Termios are used with iotcl() calls for terminal handling.
-\begin{verbatim}
-Const  NCCS = 19;
-       NCC = 8;
-         
-Type termio = record
-	c_iflag,		{ input mode flags }
-	c_oflag,		{ output mode flags }
-	c_cflag,		{ control mode flags }
-	c_lflag : Word;		{ local mode flags }
-	c_line : Word;		{ line discipline - careful, only High byte in use}
-	c_cc : array [0..NCC-1] of char;	{ control characters }
-end;
-termios = record
-  c_iflag,              { input mode flags }
-  c_oflag,              { output mode flags }
-  c_cflag,              { control mode flags }
-  c_lflag : Cardinal;	{ local mode flags }
-  c_line : char;          { line discipline }
-  c_cc : array [0..NCCS-1] of char;      { control characters }
-end;
-\end{verbatim}
-\var{Utimbuf} is used in the \seef{Utime} call to set access and modificaton time
-of a file.
-\begin{verbatim}
-utimbuf = record
-  actime,modtime : Longint;
-  end;
-\end{verbatim}
-For the \seef{Select} call, the following 4 types are needed:
-\begin{verbatim}
-FDSet = Array [0..31] of longint;
-PFDSet = ^FDSet;
-TimeVal = Record
-   sec,usec : Longint;
-end;
-PTimeVal = ^TimeVal;
-\end{verbatim}
-The \var{timespec} record is needed in the \seef{NanoSleep} function:
-\begin{verbatim}
-timespec = packed record
-  tv_sec,tv_nsec:longint;
-end;
-\end{verbatim}
-
-The \seep{Uname} function uses the \var{utsname} to return information about
-the current kernel :
-\begin{verbatim}
-utsname =record
-  sysname,nodename,release,
-  version,machine,domainname : Array[0..64] of char;
-end;
-\end{verbatim}
-Its elements are null-terminated C style strings, you cannot access them
-directly !
-
-%
-\subsection{Variables}
-\var{Linuxerror} is the variable in which the procedures in the linux unit
-report errors.
-\begin{verbatim}
-LinuxError : Longint;
-\end{verbatim}
-\var{StdErr} Is a \var{Text} variable, corresponding to Standard Error or
-diagnostic output. It is connected to file descriptor 2. It can be freely
-used, and will be closed on exit.
-\begin{verbatim}
-StdErr : Text;
-\end{verbatim}
-
-%
-\subsection{Constants}
-Constants for setting/getting process priorities :
-\begin{verbatim}
-      Prio_Process = 0;
-      Prio_PGrp    = 1;
-      Prio_User    = 2;
-\end{verbatim}
-For testing  access rights:
-\begin{verbatim}
-      R_OK = 4; 
-      W_OK = 2;
-      X_OK = 1;
-      F_OK = 0;
-\end{verbatim}
-For signal handling functions :
-\begin{verbatim}
-      SA_NOCLDSTOP = 1;
-      SA_SHIRQ	   = $04000000;
-      SA_STACK	   = $08000000;      
-      SA_RESTART   = $10000000;
-      SA_INTERRUPT = $20000000;
-      SA_NOMASK	   = $40000000;
-      SA_ONESHOT   = $80000000;
-      
-      SIG_BLOCK	  = 0;
-      SIG_UNBLOCK = 1;
-      SIG_SETMASK = 2;
-      SIG_DFL = 0 ;
-      SIG_IGN = 1 ;
-      SIG_ERR = -1;
-      
-      SIGHUP		= 1;
-      SIGINT		= 2;
-      SIGQUIT		= 3;
-      SIGILL		= 4;
-      SIGTRAP		= 5;
-      SIGABRT		= 6;
-      SIGIOT		= 6;
-      SIGBUS		= 7;
-      SIGFPE		= 8;
-      SIGKILL		= 9;
-      SIGUSR1		= 10;
-      SIGSEGV		= 11;
-      SIGUSR2		= 12;
-      SIGPIPE		= 13;
-      SIGALRM		= 14;
-      SIGTERM		= 15;
-      SIGSTKFLT		= 16;
-      SIGCHLD		= 17;
-      SIGCONT		= 18;
-      SIGSTOP		= 19;
-      SIGTSTP		= 20;
-      SIGTTIN		= 21;
-      SIGTTOU		= 22;
-      SIGURG		= 23;
-      SIGXCPU		= 24;
-      SIGXFSZ		= 25;
-      SIGVTALRM		= 26;
-      SIGPROF		= 27;
-      SIGWINCH		= 28;
-      SIGIO		= 29;
-      SIGPOLL		= SIGIO;
-      SIGPWR		= 30;
-      SIGUNUSED		= 31;
-\end{verbatim}
-For file control mechanism :
-\begin{verbatim}
-      F_GetFd  = 1;
-      F_SetFd  = 2;
-      F_GetFl  = 3;
-      F_SetFl  = 4;
-      F_GetLk  = 5;
-      F_SetLk  = 6;
-      F_SetLkW = 7;
-      F_GetOwn = 8;
-      F_SetOwn = 9;
-\end{verbatim}
-For Terminal handling :
-\begin{verbatim}
-   TCGETS	= $5401 ;
-   TCSETS	= $5402 ;
-   TCSETSW	= $5403 ;
-   TCSETSF	= $5404 ;
-   TCGETA	= $5405 ;
-   TCSETA	= $5406 ;
-   TCSETAW	= $5407 ;
-   TCSETAF	= $5408 ;
-   TCSBRK	= $5409 ;
-   TCXONC	= $540A ;
-   TCFLSH	= $540B ;
-   TIOCEXCL	= $540C ;
-   TIOCNXCL	= $540D ;
-   TIOCSCTTY	= $540E ;
-   TIOCGPGRP	= $540F ;
-   TIOCSPGRP	= $5410 ;
-   TIOCOUTQ	= $5411 ;
-   TIOCSTI	= $5412 ;
-   TIOCGWINSZ	= $5413 ;
-   TIOCSWINSZ	= $5414 ;
-   TIOCMGET	= $5415 ;
-   TIOCMBIS	= $5416 ;
-   TIOCMBIC	= $5417 ;
-   TIOCMSET	= $5418 ;
-   TIOCGSOFTCAR	= $5419 ;
-   TIOCSSOFTCAR	= $541A ;
-   FIONREAD	= $541B ;
-   TIOCINQ	= FIONREAD;
-   TIOCLINUX	= $541C ;
-   TIOCCONS	= $541D ;
-   TIOCGSERIAL	= $541E ;
-   TIOCSSERIAL	= $541F ;
-   TIOCPKT	= $5420 ;
-   FIONBIO	= $5421 ;
-   TIOCNOTTY	= $5422 ;
-   TIOCSETD	= $5423 ;
-   TIOCGETD	= $5424 ;
-   TCSBRKP		= $5425	 ;
-   TIOCTTYGSTRUCT	= $5426  ;
-   FIONCLEX	= $5450  ;
-   FIOCLEX		= $5451 ;
-   FIOASYNC	= $5452 ;
-   TIOCSERCONFIG	= $5453 ;
-   TIOCSERGWILD	= $5454 ;
-   TIOCSERSWILD	= $5455 ;
-   TIOCGLCKTRMIOS	= $5456 ;
-   TIOCSLCKTRMIOS	= $5457 ;
-   TIOCSERGSTRUCT	= $5458  ;
-   TIOCSERGETLSR   = $5459  ;
-   TIOCSERGETMULTI = $545A  ;
-   TIOCSERSETMULTI = $545B  ;
-   TIOCMIWAIT	= $545C	;
-   TIOCGICOUNT	= $545D	;
-   TIOCPKT_DATA		= 0;
-   TIOCPKT_FLUSHREAD	= 1;
-   TIOCPKT_FLUSHWRITE	= 2;
-   TIOCPKT_STOP		= 4;
-   TIOCPKT_START	= 8;
-   TIOCPKT_NOSTOP	= 16;
-   TIOCPKT_DOSTOP	= 32;
-\end{verbatim}
-Other than that, all constants for setting the speed and control flags of a
-terminal line, as described in the \seem{termios}{2} man
-page, are defined in the linux unit. It would take too much place to list
-them here. 
-To check the \var{mode} field of a \var{stat} record, you ca use the
-following constants :
-\begin{verbatim}
-  { Constants to check stat.mode }
-  STAT_IFMT   = $f000; {00170000}
-  STAT_IFSOCK = $c000; {0140000}
-  STAT_IFLNK  = $a000; {0120000}
-  STAT_IFREG  = $8000; {0100000}
-  STAT_IFBLK  = $6000; {0060000}
-  STAT_IFDIR  = $4000; {0040000}
-  STAT_IFCHR  = $2000; {0020000}
-  STAT_IFIFO  = $1000; {0010000}
-  STAT_ISUID  = $0800; {0004000}
-  STAT_ISGID  = $0400; {0002000}
-  STAT_ISVTX  = $0200; {0001000}
-  { Constants to check permissions }
-  STAT_IRWXO = $7;
-  STAT_IROTH = $4;
-  STAT_IWOTH = $2;
-  STAT_IXOTH = $1;
-  STAT_IRWXG = STAT_IRWXO shl 3;
-  STAT_IRGRP = STAT_IROTH shl 3;
-  STAT_IWGRP = STAT_IWOTH shl 3;
-  STAT_IXGRP = STAT_IXOTH shl 3;
-  STAT_IRWXU = STAT_IRWXO shl 6;
-  STAT_IRUSR = STAT_IROTH shl 6;
-  STAT_IWUSR = STAT_IWOTH shl 6;
-  STAT_IXUSR = STAT_IXOTH shl 6;
-\end{verbatim}
-You can test the type of a filesystem returned by a \seef{FSStat} call with
-the following constants:
-\begin{verbatim}
-  fs_old_ext2 = $ef51;
-  fs_ext2     = $ef53;
-  fs_ext      = $137d;
-  fs_iso      = $9660;
-  fs_minix    = $137f;
-  fs_minix_30 = $138f;
-  fs_minux_V2 = $2468;
-  fs_msdos    = $4d44;
-  fs_nfs      = $6969;
-  fs_proc     = $9fa0;
-  fs_xia      = $012FD16D;
-\end{verbatim}
-the \seef{FLock} call uses the following mode constants :
-\begin{verbatim}
-  LOCK_SH = 1;
-  LOCK_EX = 2;
-  LOCK_UN = 8;
-  LOCK_NB = 4;
-\end{verbatim}
-The \seef{MMap} function uses the following constants to specify access to
-mapped memory:
-\begin{verbatim}
-  PROT_READ  = $1;   { page can be read }
-  PROT_WRITE = $2;   { page can be written } 
-  PROT_EXEC  = $4;   { page can be executed }
-  PROT_NONE  = $0;   { page can not be accessed }
-\end{verbatim}
-and the following constants to specify the type of mapping.
-\begin{verbatim}
-  MAP_SHARED    = $1;  { Share changes }
-  MAP_PRIVATE   = $2;  { Changes are private }
-  MAP_TYPE      = $f;  { Mask for type of mapping }
-  MAP_FIXED     = $10; { Interpret addr exactly }
-  MAP_ANONYMOUS = $20; { don't use a file }
-\end{verbatim}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Functions and procedures by category
-\section{Function list by category}
-What follows is a listing of the available functions, grouped by category.
-For each function there is a reference to the page where you can find the
-function.
-\subsection{File Input/Output routines}
-Functions for handling file input/output.
-\begin{funclist}
-\funcref{Dup}{Duplicate a file handle}
-\funcref{Dup2}{Copy one file handle to another}
-\procref{Fcntl}{General file control}
-\funcref{fdClose}{Close file descriptor}
-\funcref{fdFlush}{Flush file descriptor}
-\funcref{fdOpen}{Open new file descriptor}
-\funcref{fdRead}{Read from file descriptor}
-\funcref{fdSeek}{Position in file}
-\funcref{fdTruncate}{Truncate file}
-\funcref{fdWrite}{Write to file descriptor}
-\funcref{GetFS}{Get file descriptor of pascal file}
-\funcref{Select}{Wait for input from file descriptor}
-\funcref{SelectText}{Wait for input from pascal file}
-\end{funclist}
-
-\subsection{General File handling routines}
-Functions for handling files on disk.
-\begin{funclist}
-\funcref{Access}{Check access rights on file}
-\funcref{BaseName}{Return name part of file}
-\funcref{Chown}{Change owner of file}
-\funcref{Chmod}{Change access rights on file}
-\funcref{DirName}{Return directory part of file}
-\procrefl{FSplit}{LFsplit}{Split filename in parts}
-\funcref{FExpand}{Return full-grown filename}
-\funcref{FLock}{Set lock on a file}
-\funcref{FNMatch}{Match filename to searchpattern}
-\funcref{FSearch}{Search for a file in a path}
-\funcref{FSStat}{Return filesystem information}
-\funcref{FStat}{Return file information}
-\funcref{FRename}{Rename file}
-\funcref{LStat}{Return information on a link}
-\funcref{Link}{Create a link}
-\funcref{ReadLink}{Read contents of a symbolic link}
-\funcref{SymLink}{Create a symbolic link}
-\funcref{Umask}{Set the file creation mask}
-\funcref{UnLink}{Remove a file}
-\funcref{Utime}{Change file timestamps}
-\end{funclist}
-
-\subsection{Pipes, FIFOs and streams }
-Functions for creating and managing pipes.
-\begin{funclist}
-\funcref{AssignPipe}{Create a pipe}
-\funcref{AssignStream}{Create pipes to program's input and output}
-\funcref{MkFifo}{Make a fifo}
-\funcref{PClose}{Close a pipe}
-\procref{POpen}{Open a pipe for to program's input or output}
-\end{funclist}
-
-\subsection{Directory handling routines}
-Functions for reading and searching directories.
-\begin{funclist}
-\funcref{CloseDir}{Close directory handle}
-\funcref{Glob}{Return files matching a search expression}
-\procref{GlobFree}{Free result of Glob}
-\funcref{OpenDir}{Open directory for reading}
-\funcref{ReadDir}{Read directory entry}
-\procref{SeekDir}{Seek directory}
-\funcref{TellDir}{Seek directory}
-\end{funclist}
-
-\subsection{Process handling}
-Functions for managing processes and programs.
-\begin{funclist}
-\funcref{Clone}{Create a thread}
-\procref{Execl}{Execute process with command-line list}
-\procref{Execle}{Execute process with command-line list and environment}
-\procref{Execlp}{Search in path and execute process with command list}
-\procref{Execv}{Execute process}
-\procref{Execve}{Execute process with environment}
-\procref{Execvp}{Search in path and execute process}
-\funcref{Fork}{Spawn child process}
-\funcref{GetEGid}{Get effective group id}
-\funcref{GetEnv}{Get environment variable}
-\funcref{GetEUid}{Get effective user id}
-\funcref{GetGid}{Get group id}
-\funcref{GetPid}{Get process id}
-\funcref{GetPPid}{Get parent process id}
-\funcref{GetPriority}{Get process priority}
-\funcref{GetUid}{Get user id}
-\procref{Nice}{Change priority of process}
-\funcref{SetPriority}{Change priority of process}
-\funcref{Shell}{Execute shell command}
-\funcref{WaitPid}{Wait for child process to terminate}
-\end{funclist}
-
-\subsection{Signals}
-Functions for managing and responding to signals.
-\begin{funclist}
-\funcref{Alarm}{Send alarm signal to self}
-\funcref{Kill}{Send arbitrary signal to process}
-\procref{pause}{Wait for signal to arrive}
-\procref{SigAction}{Set signal action}
-\funcref{Signal}{Set signal action}
-\funcref{SigPending}{See if signals are waiting}
-\procref{SigProcMask}{Set signal processing mask}
-\procref{SigRaise}{Send signal to self}
-\procref{SigSuspend}{Sets signal mask and waits for signal}
-\funcref{NanoSleep}{Waits for a specific amount of time}
-\end{funclist}
-
-\subsection{System information}
-Functions for retrieving system information such as date and time.
-\begin{funclist}
-\procref{GetDate}{Return system date}
-\procref{GetDateTime}{Return system date and time}
-\funcref{GetDomainName}{Return system domain name}
-\funcref{GetEpochTime}{Return epoch time}
-\funcref{GetHostName}{Return system host name}
-\procref{GetLocalTimezone}{Return system timezone}
-\procref{GetTime}{Return system time}
-\funcref{GetTimeOfDay}{Return system time}
-\funcref{GetTimezoneFile}{Return name of timezone file}
-\procref{ReadTimezoneFile}{Read timezone file contents}
-\funcref{SysInfo}{Return general system information}
-\procref{Uname}{Return system information}
-\end{funclist}
-
-\subsection{Terminal functions}
-Functions for controlling the terminal to which the process is connected.
-
-\begin{funclist}
-\procref{CFMakeRaw}{Set terminal to raw mode}
-\procref{CFSetISpeed}{Set terminal reading speed}
-\procref{CFSetOSpeed}{Set terminal writing speed}
-\procref{IOCtl}{General IO control call}
-\funcref{IsATTY}{See if filedescriptor is a terminal}
-\funcref{TCDrain}{Wait till all output was written}
-\funcref{TCFlow}{Suspend transmission or receipt of data}
-\funcref{TCFlush}{Discard data written to terminal}
-\funcref{TCGetAttr}{Get terminal attributes}
-\funcref{TCGetPGrp}{Return PID of foreground process}
-\funcref{TCSendBreak}{Send data for specific time}
-\funcref{TCSetAttr}{Set terminal attributes}
-\funcref{TCSetPGrp}{Set foreground process}
-\funcref{TTYName}{Name of tty file}
-\end{funclist}
-
-\subsection{Port input/output}
-Functions for reading and writing to the hardware ports.
-\begin{funclist}
-\funcref{IOperm}{Set permissions for port access}
-\procref{ReadPort}{Read data from port}
-\procref{ReadPortB}{Read 1 byte from port}
-\procref{ReadPortL}{Read 4 bytes from port}
-\procref{ReadPortW}{Read 2 bytes from port}
-\procref{WritePort}{Write data to port}
-\procref{WritePortB}{Write 1 byte to port}
-\procref{WritePortL}{Write 4 bytes to port}
-\procref{WritePortW}{Write 2 bytes to port}
-\end{funclist}
-
-\subsection{Utility routines}
-Auxiliary functions that are useful in connection with the other functions.
-\begin{funclist}
-\funcref{CreateShellArgV}{Create an array of pchars from string}
-\procref{EpochToLocal}{Convert epoch time to local time}
-\procrefl{FD\_Clr}{FDClr}{Clear item of select filedescriptors}
-\funcrefl{FD\_IsSet}{FDIsSet}{Check item of select filedescriptors}
-\procrefl{FD\_Set}{FDSet}{Set item of select filedescriptors}
-\procrefl{FD\_ZERO}{FDZero}{Clear all items in select filedecriptors}
-\funcref{LocalToEpoch}{Convert local time to epoch time}
-\funcref{MMap}{Map a file into memory}
-\funcref{MUnMap}{Unmap previously mapped memory file}
-\funcref{Octal}{Convert octal to digital}
-\funcrefl{S\_ISBLK}{ISBLK}{Check file mode for block device}
-\funcrefl{S\_ISCHR}{ISCHR}{Check file mode for character device}
-\funcrefl{S\_ISDIR}{ISDIR}{Check file mode for directory}
-\funcrefl{S\_ISFIFO}{ISFIFO}{Check file mode for FIFO}
-\funcrefl{S\_ISLNK}{ISLNK}{Check file mode for symboloc link}
-\funcrefl{S\_ISREG}{ISREG}{Check file mode for regular file}
-\funcrefl{S\_ISSOCK}{ISSOCK}{Check file mode for socket}
-\funcref{StringToPPchar}{Create an array of pchars from string}
-\end{funclist}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Functions and procedures
-\section{Functions and procedures}
-
-\begin{function}{Access}
-\Declaration
-Function Access (Path : Pathstr; Mode : integer) : Boolean;
-\Description
-Tests user's access rights on the specified file. Mode is a mask existing of
-one or more of
-\begin{description}
-\item[R\_OK] User has read rights.
-\item[W\_OK] User has write rights.
-\item[X\_OK] User has execute rights.
-\item[F\_OK] User has search rights in the directory where the file is.
-\end{description}
-The test is done with the real user ID, instead of the effective user ID.
-If access is denied, or an error occurred, false is returned.
-\Errors
- \var{LinuxError} is used to report errors:
-\begin{description}
-\item[sys\_eaccess] The requested access is denied, either to the file or one
-of the directories in its path.
-\item[sys\_einval] \var{Mode} was incorrect.
-\item[sys\_enoent] A directory component in \var{Path} doesn't exist or is a
-dangling symbolic link.
-\item[sys\_enotdir] A directory component in \var{Path} is not a directory.
-\item[sys\_enomem] Insufficient kernel memory.
-\item[sys\_eloop] \var{Path} has a circular symbolic link.
-\end{description}
-
-\SeeAlso
-\seef{Chown}, \seef{Chmod}, \seem{Access}{2} 
-\end{function}
-
-
-\FPCexample{ex26}
-
-
-\begin{function}{Alarm}
-\Declaration
-Function Alarm(Sec : longint) : Longint;
-\Description
-Alarm schedules an alarm signal to be delivered to your process in \var{Sec}
-seconds. When \var{Sec} seconds have elapsed, Linux will send a \var{SIGALRM}
-signal to the current process.  If \var{Sec} is zero, then no new alarm will
-be set. Whatever the value of \var{Sec}, any previous alarm is cancelled.
-
-The function returns the number of seconds till the previously scheduled
-alarm was due to be delivered, or zero if there was none.
-\Errors{None}
-\end{function}
-
-
-\FPCexample{ex59}
-
-
-\begin{function}{AssignPipe}
-\Declaration
-Function  AssignPipe(var pipe\_in,pipe\_out:longint):boolean;
-Function  AssignPipe(var pipe\_in,pipe\_out:text):boolean;
-Function  AssignPipe(var pipe\_in,pipe\_out:file):boolean;
-\Description
-\var{AssignePipe} creates a pipe, i.e. two file objects, one for input, 
-one for output. What is written to \var{Pipe\_out}, can be read from 
-\var{Pipe\_in}. 
-
-This call is overloaded. The in and out pipe can take three forms:
-an typed or untyped file, a text file or a file descriptor.
-
-If a text file is passed then reading and writing from/to the pipe 
-can be done through the usual \var{Readln(Pipe\_in,...)} and
-\var{Writeln (Pipe\_out,...)} procedures.
-
-The function returns \var{True} if everything went succesfully,
-\var{False} otherwise.
-\Errors
-In case the function fails and returns \var{False}, \var{LinuxError} 
-is used to report errors:
-\begin{description}
-\item[sys\_emfile] Too many file descriptors for this process.
-\item[sys\_enfile] The system file table is full.
-\end{description}
-\SeeAlso
-\seep{POpen}, \seef{MkFifo}, \seem{pipe}{2}
-\end{function}
-
-
-\FPCexample{ex36}
-
-
-\begin{function}{AssignStream}
-\Declaration
-Function AssignStream(Var StreamIn,Streamout:text;
-                      Const Prog:String) : longint;
-Function AssignStream(var StreamIn, StreamOut, StreamErr: Text; 
-                      const prog: String): LongInt;
-\Description
-\var{AssignStream} creates a 2 or 3 pipes, i.e. two (or three) file objects, one for 
-input, one for output,(and one for standard error) the other ends of these 
-pipes are connected to standard input and output (and standard error) of 
-\var{Prog}. \var{Prog} is the name of a program (including path) with options,
- which will be executed.
-
-What is written to \var{StreamOut}, will go to the standard input of
-\var{Prog}. Whatever is written by \var{Prog} to it's standard output 
-can be read from \var{StreamIn}. 
-Whatever is written by \var{Prog} to it's standard error read from 
-\var{StreamErr}, if present. 
-
-Reading and writing happens through the usual \var{Readln(StreamIn,...)} and
-\var{Writeln (StreamOut,...)} procedures.
-
-{\em Remark:} You should {\em not} use \var{Reset} or \var{Rewrite} on a 
-file opened with \var{POpen}. This will close the file before re-opening 
-it again, thereby closing the connection with the program.
-
-The function returns the process ID of the spawned process, or -1 in case of
-error.
-
-\Errors
-In case of error (return value -1) \var{LinuxError} is used to report 
-errors:
-\begin{description}
-\item[sys\_emfile] Too many file descriptors for this process.
-\item[sys\_enfile] The system file table is full.
-\end{description}
-Other errors include the ones by the fork and exec programs
-\SeeAlso
-\seef{AssignPipe}, \seep{POpen},\seem{pipe}{2}
-\end{function}
-
-
-\FPCexample{ex38}
-
-
-\begin{function}{BaseName}
-\Declaration
-Function BaseName (Const Path;Const Suf : Pathstr) : Pathstr;
-\Description
-Returns the filename part of \var{Path}, stripping off \var{Suf} if it
-exists.
-The filename part is the whole name if \var{Path} contains no slash,
-or the part of \var{Path} after the last slash.
-The last character of the result is not a slash, unless the directory is the
-root directory.
-
-\Errors
-None.
-\SeeAlso
-\seef{DirName}, \seef{FExpand}, \seem{Basename}{1}
-\end{function}
-
-\FPCexample{ex48}
-
-\begin{procedure}{CFMakeRaw}
-\Declaration
-Procedure CFMakeRaw (var Tios:TermIOS);
-\Description
- \var{CFMakeRaw}
-  Sets the flags in the \var{Termios} structure \var{Tios} to a state so that 
-  the terminal will function in Raw Mode.
-
-\Errors
-None.
-\SeeAlso
- \seep{CFSetOSpeed}, \seep{CFSetISpeed}, \seem{termios}{2}
-\end{procedure}
-For an example, see \seef{TCGetAttr}.
-
-\begin{procedure}{CFSetISpeed}
-\Declaration
-Procedure CFSetISpeed (var Tios:TermIOS;Speed:Longint);
-\Description
- \var{CFSetISpeed}
-  Sets the input baudrate in the \var{TermIOS} structure \var{Tios} to 
-  \var{Speed}.
-
-\Errors
-None.
-\SeeAlso
-\seep{CFSetOSpeed}, \seep{CFMakeRaw}, \seem{termios}{2}
-\end{procedure}
-
-\begin{procedure}{CFSetOSpeed}
-\Declaration
-Procedure CFSetOSpeed (var Tios:TermIOS;Speed:Longint);
-\Description
- \var{CFSetOSpeed}
-  Sets the output baudrate in the \var{Termios} structure \var{Tios} to
-  \var{Speed}.
-
-\Errors
-None.
-\SeeAlso
-\seep{CFSetISpeed}, \seep{CFMakeRaw}, \seem{termios}{2}
-\end{procedure}
-
-\begin{function}{Chown}
-\Declaration
-Function Chown (Path : Pathstr;NewUid,NewGid : Longint) : Boolean;
-\Description
- \var{Chown} sets the User ID and Group ID of the file in \var{Path} to \var{NewUid,
-NewGid}.
-The function returns \var{True} if the call was succesfull, \var{False} if the call
-failed.
-\Errors
-Errors are returned in \var{LinuxError}.
-\begin{description}
-\item[sys\_eperm] The effective UID doesn't match the ownership of the file,
-and is not zero. Owner or group were not specified correctly.
-\item[sys\_eaccess] One of the directories in \var{Path} has no
-search (=execute) permission.
-\item[sys\_enoent] A directory entry in \var{Path} does
-not exist or is a symbolic link pointing to a non-existent directory.
-\item[sys\_enotdir] A directory entry in \var{OldPath} or \var{NewPath} is
-nor a directory.
-\item[sys\_enomem] Insufficient kernel memory.
-\item[sys\_erofs] The file is on a read-only filesystem.
-\item[sys\_eloop] \var{Path} has a reference to a circular
-symbolic link, i.e. a symbolic link, whose expansion points to itself.
-\end{description}
-\SeeAlso
-\seef{Chmod}, \seef{Access}, \seem{Chown}(2)
-\end{function}
-
-\FPCexample{ex24}
-
-\begin{function}{Chmod}
-\Declaration
-Function Chmod (Path : Pathstr;NewMode : Longint) : Boolean;
-\Description
- \var{Chmod}
-Sets the Mode bits of the file in \var{Path} to \var{NewMode}. Newmode can be
-specified by 'or'-ing the following:
-\begin{description}
-\item[S\_ISUID] Set user ID on execution.
-\item[S\_ISGID] Set Group ID on execution.
-\item[S\_ISVTX] Set sticky bit.
-\item[S\_IRUSR] Read by owner.
-\item[S\_IWUSR] Write by owner.
-\item[S\_IXUSR] Execute by owner.
-\item[S\_IRGRP] Read by group.
-\item[S\_IWGRP] Write by group.
-\item[S\_IXGRP] Execute by group.
-\item[S\_IROTH] Read by others.
-\item[S\_IWOTH] Write by others.
-\item[S\_IXOTH] Execute by others.
-\item[S\_IRWXO] Read, write, execute by others.
-\item[S\_IRWXG] Read, write, execute by groups.
-\item[S\_IRWXU] Read, write, execute by user.
-\end{description}
-
-\Errors
-Errors are returned in \var{LinuxError}.
-\begin{description}
-\item[sys\_eperm] The effective UID doesn't match the ownership of the file,
-and is not zero. Owner or group were not specified correctly.
-\item[sys\_eaccess] One of the directories in \var{Path} has no
-search (=execute) permission.
-\item[sys\_enoent] A directory entry in \var{Path} does
-not exist or is a symbolic link pointing to a non-existent directory.
-\item[sys\_enotdir] A directory entry in \var{OldPath} or \var{NewPath} is
-nor a directory.
-\item[sys\_enomem] Insufficient kernel memory.
-\item[sys\_erofs] The file is on a read-only filesystem.
-\item[sys\_eloop] \var{Path} has a reference to a circular
-symbolic link, i.e. a symbolic link, whose expansion points to itself.
-\end{description}
-
-\SeeAlso
-\seef{Chown}, \seef{Access}, \seem{Chmod}(2), \seef{Octal}
-\end{function}
-
-\FPCexample{ex23}
-
-\begin{function}{Clone}
-\Declaration
-TCloneFunc=function(args:pointer):longint;cdecl;
-Clone(func:TCloneFunc;sp:pointer;flags:longint;args:pointer):longint;
-\Description
-Clone creates a child process which is a copy of the parent process, just
-like \seef{Fork} does. In difference with \var{Fork}, however, the child
-process shares some parts of it's execution context with its parent, so it
-is suitable for the implementation of threads: many instances of a program
-that share the same memory.
-
-When the child process is created, it starts executing the function
-\var{Func}, and passes it \var{Args}. The return value of \var{Func} is 
-either the explicit return value of the function, or the exit code of
-the child process.
-
-The \var{sp} pointer points to the memory reserved as stack space for the
-child process. This address should be the top of the memory block to be used
-as stack.
-
-The \var{Flags} determine the behaviour of the \var{Clone} call. The low
-byte of the Flags contains the number of the signal that will be  sent to 
-the parent when  the child dies. 
-This may be bitwise OR'ed with the following constants:
-\begin{description}
-\item[CLONE\_VM] Parent and child share the same memory space, including
-memory (un)mapped with subsequent \var{mmap} calls.
-\item[CLONE\_FS] Parent and child have the same view of the filesystem;
-the \var{chroot}, \var{chdir} and \var{umask} calls affect both processes.
-\item[CLONE\_FILES] the file descriptor table of parent and child is shared. 
-\item[CLONE\_SIGHAND] the parent and child share the same table of signal
-handlers. The signal masks are different, though.
-\item[CLONE\_PID] PArent and child have the same process ID.
-\end{description}
-
-Clone returns the process ID in the parent process, and -1 if an error
-occurred.
-\Errors
-On error, -1 is returned to the parent, and no child is created.
-\begin{description}
-\item [sys\_eagain] Too many processes are running.
-\item [sys\_enomem] Not enough memory to create child process.
-\end{description}
-\SeeAlso
-\seef{Fork}, \seem{clone}{2}
-\end{function}
-
-\FPCexample{ex71}
-
-\begin{function}{CloseDir}
-\Declaration
-Function CloseDir (p:pdir) : integer;
-\Description
- \var{CloseDir} closes the directory pointed to by \var{p}.
-It returns zero if the directory was closed succesfully, -1 otherwise.
-\Errors
-Errors are returned in LinuxError.
-\SeeAlso
-\seef{OpenDir}, \seef{ReadDir}, \seep{SeekDir}, \seef{TellDir},
-\seem{closedir}{3}
-\end{function}
-For an example, see \seef{OpenDir}.
-
-\begin{function}{CreateShellArgV}
-\Declaration
-function  CreateShellArgV(const prog:string):ppchar;
-function  CreateShellArgV(const prog:Ansistring):ppchar;
-\Description
-\var{CreateShellArgV} creates an array of 3 \var{PChar} pointers that can
-be used as arguments to \var{ExecVE} the first elements in the array 
-will contain  \var{/bin/sh}, the second will contain \var{-c}, and the third
-will contain \var{prog}.
-
-The function returns a pointer to this array, of type \var{PPChar}.
-\Errors
-None.
-\SeeAlso
-\seef{Shell}
-\end{function}
-
-\FPCexample{ex61}
-
-\begin{function}{DirName}
-\Declaration
-Function DirName (Const Path : Pathstr) : Pathstr;
-\Description
-Returns the directory part of \var{Path}.
-The directory is the part of \var{Path} before the last slash,
-or empty if there is no slash.
-The last character of the result is not a slash, unless the directory is the
-root directory.
-
-\Errors
-None.
-\SeeAlso
-\seef{BaseName}, \seef{FExpand}, \seem{Dirname}{1}
-\end{function}
-
-\FPCexample{ex47}
-
-
-\begin{function}{Dup}
-\Declaration
-Function  Dup(oldfile:longint;var newfile:longint):Boolean;
-Function  Dup(var oldfile,newfile:text):Boolean;
-Function  Dup(var oldfile,newfile:file):Boolean;
-\Description
-Makes \var{NewFile} an exact copy of \var{OldFile}, after having flushed the
-buffer of \var{OldFile} in case it is a Text file or untyped file. 
-Due to the buffering mechanism of Pascal, this has not the same functionality
-as the \seem{dup}{2} call in C. The internal Pascal buffers are not the same 
-after this call, but when the buffers are flushed (e.g. after output), 
-the output is sent to the same file.
-Doing an lseek will, however, work as in C, i.e. doing a lseek will change 
-the fileposition in both files.
-
-The function returns \var{False} in case of an error, \var{True} if
-successful.
-\Errors
-In case of errors, \var{Linuxerror} is used to report errors.
-\begin{description}
-\item[sys\_ebadf] \var{OldFile} hasn't been assigned.
-\item[sys\_emfile] Maximum number of open files for the process is reached.
-\end{description}
-\SeeAlso
-\seef{Dup2}, \seem{Dup}{2} 
-\end{function}
-
-
-\FPCexample{ex31}
-
-
-\begin{function}{Dup2}
-\Declaration
-Function  Dup2(oldfile,newfile:longint):Boolean;
-Function  Dup2(var oldfile,newfile:text):Boolean;
-Function  Dup2(var oldfile,newfile:file):Boolean;
-\Description
-Makes \var{NewFile} an exact copy of \var{OldFile}, after having flushed the
-buffer of \var{OldFile} in the case of text or untyped files. 
-
-\var{NewFile} can be an assigned file. If \var{newfile} was open, it is 
-closed first. Due to the buffering mechanism of Pascal, this has not
-the same functionality as the \seem{dup2}{2} call in C. The internal Pascal
-buffers are not the same after this call, but when the buffers are flushed
-(e.g. after output), the output is sent to the same file.
-Doing an lseek will, however, work as in C, i.e. doing a lseek will change the
-fileposition in both files.
-
-The function returns \var{True} if succesful, false otherwise.
-\Errors
-In case of error, \var{Linuxerror} is used to report errors.
-\begin{description}
-\item[sys\_ebadf] \var{OldFile} hasn't been assigned.
-\item[sys\_emfile] Maximum number of open files for the process is reached.
-\end{description}
-\SeeAlso
- \seef{Dup}, \seem{Dup2}{2} 
-\end{function}
-
-
-\FPCexample{ex32}
-
-
-\begin{procedure}{EpochToLocal}
-\Declaration
-Procedure EpochToLocal (Epoch : Longint; var Year,Month,Day,Hour,Minute,Second : Word);
-\Description
-Converts the epoch time (=Number of seconds since 00:00:00 , January 1,
-1970, corrected for your time zone ) to local date and time.
-
-This function takes into account the timzeone settings of your system.
-\Errors
-None
-\SeeAlso
-\seef{GetEpochTime}, \seef{LocalToEpoch}, \seep{GetTime},\seep{GetDate} 
-\end{procedure}
-
-\FPCexample{ex3}
-
-\begin{procedure}{Execl}
-\Declaration
-Procedure Execl (Path : pathstr);
-\Description
-Replaces the currently running program with the program, specified in
-\var{path}. Path is split into a command and it's options.
-The executable in \var{path} is NOT searched in the path.
-The current environment is passed to the program.
-On success, \var{execl} does not return.
-
-\Errors
-Errors are reported in \var{LinuxError}:
-\begin{description}
-\item[sys\_eacces] File is not a regular file, or has no execute permission.
-A compononent of the path has no search permission.
-\item[sys\_eperm] The file system is mounted \textit{noexec}.
-\item[sys\_e2big] Argument list too big.
-\item[sys\_enoexec] The magic number in the file is incorrect.
-\item[sys\_enoent] The file does not exist.
-\item[sys\_enomem] Not enough memory for kernel, or to split command line.
-\item[sys\_enotdir] A component of the path is not a directory.
-\item[sys\_eloop] The path contains a circular reference (via symlinks).
-\end{description}
-\SeeAlso
-\seep{Execve}, \seep{Execv}, \seep{Execvp}, \seep{Execle},
- \seep{Execlp}, \seef {Fork}, \seem{execvp}{3} 
-\end{procedure}
-
-\FPCexample{ex10}
-
-\begin{procedure}{Execle}
-\Declaration
-Procedure Execle (Path : pathstr, Ep : ppchar);
-\Description
-Replaces the currently running program with the program, specified in
-\var{path}. Path is split into a command and it's options.
-The executable in \var{path} is searched in the path, if it isn't
-an absolute filename.
-The environment in \var{ep} is passed to the program.
-On success, \var{execle} does not return.
-
-\Errors
-Errors are reported in \var{LinuxError}:
-\begin{description}
-\item[sys\_eacces] File is not a regular file, or has no execute permission.
-A compononent of the path has no search permission.
-\item[sys\_eperm] The file system is mounted \textit{noexec}.
-\item[sys\_e2big] Argument list too big.
-\item[sys\_enoexec] The magic number in the file is incorrect.
-\item[sys\_enoent] The file does not exist.
-\item[sys\_enomem] Not enough memory for kernel, or to split command line.
-\item[sys\_enotdir] A component of the path is not a directory.
-\item[sys\_eloop] The path contains a circular reference (via symlinks).
-\end{description}
-\SeeAlso
-\seep{Execve}, \seep{Execv}, \seep{Execvp},
-\seep{Execl}, \seep{Execlp}, \seef {Fork}, \seem{execvp}{3} 
-\end{procedure}
-
-\FPCexample{ex11}
-
-\begin{procedure}{Execlp}
-\Declaration
-Procedure Execlp (Path : pathstr);
-\Description
-Replaces the currently running program with the program, specified in
-\var{path}. Path is split into a command and it's options.
-The executable in \var{path} is searched in the path, if it isn't
-an absolute filename.
-The current environment is passed to the program.
-On success, \var{execlp} does not return.
-
-\Errors
-Errors are reported in \var{LinuxError}:
-\begin{description}
-\item[sys\_eacces] File is not a regular file, or has no execute permission.
-A compononent of the path has no search permission.
-\item[sys\_eperm] The file system is mounted \textit{noexec}.
-\item[sys\_e2big] Argument list too big.
-\item[sys\_enoexec] The magic number in the file is incorrect.
-\item[sys\_enoent] The file does not exist.
-\item[sys\_enomem] Not enough memory for kernel, or to split command line.
-\item[sys\_enotdir] A component of the path is not a directory.
-\item[sys\_eloop] The path contains a circular reference (via symlinks).
-\end{description}
-\SeeAlso
-\seep{Execve}, \seep{Execv}, \seep{Execvp}, \seep{Execle},
-\seep{Execl}, \seef {Fork}, \seem{execvp}{3} 
-\end{procedure}
-
-\FPCexample{ex12}
-
-\begin{procedure}{Execv}
-\Declaration
-Procedure Execv (Path : pathstr; args : ppchar);
-\Description
-Replaces the currently running program with the program, specified in
-\var{path}.
-It gives the program the options in \var{args}.
-This is a pointer to an array of pointers to null-terminated
-strings. The last pointer in this array should be nil.
-The current environment is passed to the program.
-On success, \var{execv} does not return.
-
-\Errors
-Errors are reported in \var{LinuxError}:
-\begin{description}
-\item[sys\_eacces] File is not a regular file, or has no execute permission.
-A compononent of the path has no search permission.
-\item[sys\_eperm] The file system is mounted \textit{noexec}.
-\item[sys\_e2big] Argument list too big.
-\item[sys\_enoexec] The magic number in the file is incorrect.
-\item[sys\_enoent] The file does not exist.
-\item[sys\_enomem] Not enough memory for kernel.
-\item[sys\_enotdir] A component of the path is not a directory.
-\item[sys\_eloop] The path contains a circular reference (via symlinks).
-\end{description}
-\SeeAlso
-\seep{Execve}, \seep{Execvp}, \seep{Execle},
-\seep{Execl}, \seep{Execlp}, \seef {Fork}, \seem{execv}{3} 
-\end{procedure}
-
-\FPCexample{ex8}
-
-
-\begin{procedure}{Execve}
-\Declaration
-Procedure Execve(Path:pchar;args:ppchar;ep:ppchar);
-Procedure Execve (Path : pathstr; args,ep : ppchar);
-\Description
-Replaces the currently running program with the program, specified in
-\var{path}.
-It gives the program the options in \var{args}, and the environment in
-\var{ep}. They are pointers to an array of pointers to null-terminated
-strings. The last pointer in this array should be nil.
-On success, \var{execve} does not return.
-\Errors
-Errors are reported in \var{LinuxError}:
-\begin{description}
-\item[eacces] File is not a regular file, or has no execute permission.
-A compononent of the path has no search permission.
-\item[sys\_ eperm] The file system is mounted \textit{noexec}.
-\item[sys\_ e2big] Argument list too big.
-\item[sys\_ enoexec] The magic number in the file is incorrect.
-\item[sys\_ enoent] The file does not exist.
-\item[sys\_ enomem] Not enough memory for kernel.
-\item[sys\_ enotdir] A component of the path is not a directory.
-\item[sys\_ eloop] The path contains a circular reference (via symlinks).
-\end{description}
-\SeeAlso
-\seep{Execve}, \seep{Execv}, \seep{Execvp} \seep{Execle},
-\seep{Execl}, \seep{Execlp}, \seef {Fork}, \seem{execve}{2} 
-\end{procedure}
-
-\FPCexample{ex7}
-
-\begin{procedure}{Execvp}
-\Declaration
-Procedure Execvp (Path : pathstr; args : ppchar);
-\Description
-Replaces the currently running program with the program, specified in
-\var{path}. The executable in \var{path} is searched in the path, if it isn't
-an absolute filename.
-It gives the program the options in \var{args}. This is a pointer to an array of pointers to null-terminated
-strings. The last pointer in this array should be nil.
-The current environment is passed to the program.
-On success, \var{execvp} does not return.
-
-\Errors
-Errors are reported in \var{LinuxError}:
-\begin{description}
-\item[sys\_eacces] File is not a regular file, or has no execute permission.
-A compononent of the path has no search permission.
-\item[sys\_eperm] The file system is mounted \textit{noexec}.
-\item[sys\_e2big] Argument list too big.
-\item[sys\_enoexec] The magic number in the file is incorrect.
-\item[sys\_enoent] The file does not exist.
-\item[sys\_enomem] Not enough memory for kernel.
-\item[sys\_enotdir] A component of the path is not a directory.
-\item[sys\_eloop] The path contains a circular reference (via symlinks).
-\end{description}
-\SeeAlso
-\seep{Execve}, \seep{Execv}, \seep{Execle},
-\seep{Execl}, \seep{Execlp}, \seef {Fork}, \seem{execvp}{3} 
-\end{procedure}
-
-\FPCexample{ex9}
-
-
-\begin{procedurel}{FD\_ZERO}{FDZero}
-\Declaration
-Procedure FD\_ZERO (var fds:fdSet);
-\Description
-\var{FD\_ZERO} clears all the filedescriptors in the file descriptor 
-set \var{fds}.
-\Errors
-None.
-\SeeAlso
-\seef{Select}, 
-\seef{SelectText}, 
-\seef{GetFS}, 
-\seepl{FD\_Clr}{FDClr},
-\seepl{FD\_Set}{FDSet}, 
-\seefl{FD\_IsSet}{FDIsSet}
-
-\end{procedurel}
-For an example, see \seef{Select}.
-
-\begin{procedurel}{FD\_Clr}{FDClr}
-\Declaration
-Procedure FD\_Clr (fd:longint;var fds:fdSet);
-\Description
- \var{FD\_Clr} clears file descriptor \var{fd} in filedescriptor s
-  et \var{fds}.
-\Errors
-None.
-\SeeAlso
-\seef{Select}, 
-\seef{SelectText}, 
-\seef{GetFS},
-\seepl{FD\_ZERO}{FDZero}, 
-\seepl{FD\_Set}{FDSet}, 
-\seefl{FD\_IsSet}{FDIsSet}
-\end{procedurel}
-
-For an example, see \seef{Select}.
-
-\begin{functionl}{FD\_IsSet}{FDIsSet}
-\Declaration
-Function FD\_IsSet (fd:longint;var fds:fdSet) : boolean;
-\Description
-\var{FD\_Set} Checks whether file descriptor \var{fd} in filedescriptor set \var{fds}
-is set.
-\Errors
-None.
-\SeeAlso
-\seef{Select}, \seef{SelectText}, \seef{GetFS},
-\seepl{FD\_ZERO}{FDZero}, 
-\seepl{FD\_Clr}{FDClr},
-\seepl{FD\_Set}{FDSet}
-\end{functionl}
-
-For an example, see \seef{Select}.
-
-\begin{procedurel}{FD\_Set}{FDSet}
-\Declaration
-Procedure FD\_Set (fd:longint;var fds:fdSet);
-\Description
-\var{FD\_Set} sets file descriptor \var{fd} in filedescriptor set \var{fds}.
-\Errors
-None.
-\SeeAlso
-\seef{Select}, \seef{SelectText}, \seef{GetFS},\seepl{FD\_ZERO}{FDZero}, 
-\seepl{FD\_Clr}{FDClr}, \seefl{FD\_IsSet}{FDIsSet}
-\end{procedurel}
-
-For an example, see \seef{Select}.
-
-\begin{function}{fdClose}
-\Declaration
-Function fdClose (fd:longint) : boolean;
-\Description
-\var{fdClose} closes a file with file descriptor \var{Fd}. The function
-returns \var{True} if the file was closed successfully, \var{False}
-otherwise. 
-
-\Errors
-Errors are returned in LinuxError
-\SeeAlso
-\seef{fdOpen}, \seef{fdRead}, \seef{fdWrite},\seef{fdTruncate},
-\seef{fdFlush}, seef{FdSeek}
-\end{function}
-For an example, see \seef{fdOpen}.
-
-\begin{function}{fdFlush}
-\Declaration
-Function fdFlush (fd:Longint) : boolean;
-\Description
-\var{fdflush} flushes the Linux kernel file buffer, so the file is actually
-written to disk. This is NOT the same as the internal buffer, maintained by
-Free Pascal. 
-The function returns \var{True} if the call was successful, \var{false} if
-an error occurred.
-\Errors
-Errors are returned in LinuxError.
-\SeeAlso
-\seef{fdOpen}, \seef{fdClose}, \seef{fdRead},\seef{fdWrite},
-\seef{fdTruncate}, \seef{fdSeek}
-\end{function}
-For an example, see \seef{fdRead}.
-
-\begin{function}{fdOpen}
-\Declaration
-Function fdOpen(PathName:String;flags:longint):longint;
-Function fdOpen(PathName:Pchar ;flags:longint):longint;
-Function fdOpen(PathName:String;flags,mode:longint):longint; 
-Function fdOpen(PathName:Pchar ;flags,mode:longint):longint;
-\Description
-\var{fdOpen} opens a file in \var{PathName} with flags \var{flags} 
-One of the following:
-\begin{description}
-\item [Open\_RdOnly] File is opened Read-only.
-\item [Open\_WrOnly] File is opened Write-only.
-\item [Open\_RdWr] File is opened Read-Write.
-\end{description}
-The flags may be\var{OR}-ed with one of the following constants:
-\begin{description}
-\item [Open\_Accmode] File is opened
-\item [Open\_Creat] File is created if it doesn't exist.
-\item [Open\_Excl] If the file is opened with \var{Open\_Creat} and it 
-already exists, the call wil fail.
-\item [Open\_NoCtty] If the file is a terminal device, it will NOT become
-the process' controlling terminal.
-\item [Open\_Trunc] If the file exists, it will be truncated.
-\item [Open\_Append] the file is opened in append mode. {\em Before each
-write}, the file pointer is positioned at the end of the file.
-\item [Open\_NonBlock] The file is opened in non-blocking mode. No operation
-on the file descriptor will cause the calling process to wait till.
-\item [Open\_NDelay] Idem as \var{Open\_NonBlock}
-\item [Open\_Sync] The file is opened for synchronous IO. Any write
-operation on the file will not return untill the data is physically written
-to disk.
-\item [Open\_NoFollow] if the file is a symbolic link, the open fails.
-(\linux 2.1.126 and higher only)
-\item [Open\_Directory] if the file is not a directory, the open fails.
-(\linux 2.1.126 and higher only)
-\end{description}
-\var{PathName} can be of type \var{PChar} or \var{String}.
-The optional \var{mode} argument specifies the permissions to set when opening
-the file. This is modified by the umask setting. The real permissions are
-\var{Mode and not umask}.
-The return value of the function is the filedescriptor, or a negative 
-value if there was an error.
-
-\Errors
-Errors are returned in LinuxError
-\SeeAlso
-\seef{fdClose}, \seef{fdRead}, \seef{fdWrite},\seef{fdTruncate},
-\seef{fdFlush}, \seef{fdSeek}
-\end{function}
-
-\FPCexample{ex19}
-
-\begin{function}{fdRead}
-\Declaration
-Function fdRead (fd:longint;var buf;size:longint) : longint;
-\Description
- \var{fdRead} reads at most \var{size} bytes from the file descriptor
-\var{fd}, and stores them in \var{buf}. 
-The function returns the number of bytes actually read, or -1 if
-an error occurred.
-No checking on the length of \var{buf} is done.
-
-\Errors
-Errors are returned in LinuxError.
-\SeeAlso
-\seef{fdOpen}, \seef{fdClose}, \seef{fdWrite},\seef{fdTruncate},
-\seef{fdFlush}, \seef{fdSeek}
-\end{function}
-
-\FPCexample{ex20}
-
-\begin{function}{fdSeek}
-\Declaration
-Function fdSeek (fd,Pos,SeekType:longint) : longint;
-\Description
-\var{fdSeek} sets the current fileposition of file \var{fd} to
-\var{Pos}, starting from \var{SeekType}, which can be one of the following:
-\begin{description}
-\item [Seek\_Set] \ \var{Pos} is the absolute position in the file.
-\item [Seek\_Cur] \ \var{Pos} is relative to the current position.
-\item [Seek\_end] \ \var{Pos} is relative to the end of the file.
-\end{description}
-The function returns the new fileposition, or -1 of an error occurred.
-
-\Errors
-Errors are returned in LinuxError.
-\SeeAlso
-\seef{fdOpen}, \seef{fdWrite}, \seef{fdClose},
-\seef{fdRead},\seef{fdTruncate},
- \seef{fdFlush}
-\end{function}
-For an example, see \seef{fdOpen}.
-
-\begin{function}{fdTruncate}
-\Declaration
-Function fdTruncate (fd,size:longint) : boolean;
-\Description
-\var{fdTruncate} sets the length of a file in \var{fd} on \var{size}
-bytes, where \var{size} must be less than or equal to the current length of
-the file in \var{fd}.
-The function returns \var{True} if the call was successful, \var{false} if
-an error occurred.
-\Errors
-Errors are returned in LinuxError.
-\SeeAlso
-\seef{fdOpen}, \seef{fdClose}, \seef{fdRead},\seef{fdWrite},\seef{fdFlush},
-\seef{fdSeek}
-\end{function}
-
-\begin{function}{fdWrite}
-\Declaration
-Function fdWrite (fd:longint;var buf;size:longint) : longint;
-\Description
-\var{fdWrite} writes at most \var{size} bytes from \var{buf} to
-file descriptor \var{fd}.
-The function returns the number of bytes actually written, or -1 if an error
-occurred.
-
-\Errors
-Errors are returned in LinuxError.
-\SeeAlso
-\seef{fdOpen}, \seef{fdClose}, \seef{fdRead},\seef{fdTruncate},
-\seef{fdSeek}, \seef{fdFlush}
-\end{function}
-
-\begin{function}{FExpand}
-\Declaration
-Function FExpand (Const Path: Pathstr) : pathstr;
-\Description
- Expands \var {Path} to a full path, starting from root,
-eliminating directory references such as . and .. from the result.
-
-\Errors
-None
-\SeeAlso
-\seef{BaseName},\seef{DirName} 
-\end{function}
-
-\FPCexample{ex45}
-
-\begin{function}{FLock}
-\Declaration
-Function  Flock (fd,mode : longint) : boolean;
-Function  Flock (var T : text;mode : longint) : boolean;
-Function  Flock (var F : File;mode : longint) : boolean;
-\Description
-\var{FLock} implements file locking. it sets or removes a lock on the file
-\var{F}. F can be of type \var{Text} or \var{File}, or it can be a \linux
-filedescriptor (a longint)
-\var{Mode} can be one of the following constants :
-\begin{description}
-\item [LOCK\_SH] \ sets a shared lock.
-\item [LOCK\_EX] \ sets an exclusive lock.
-\item [LOCK\_UN] \ unlocks the file.
-\item [LOCK\_NB] \ This can be OR-ed together with the other. 
-If this is done the application doesn't block when locking.
-\end{description}
-
-The function returns \var{True} if successful, \var{False} otherwise.
-\Errors
-If an error occurs, it is reported in \var{LinuxError}.
-\SeeAlso
-\seef{Fcntl}, \seem{flock}{2}
-\end{function}
-
-\begin{function}{FNMatch}
-\Declaration
-Function FNMatch(const Pattern,Name:string):Boolean;
-\Description
-\var{FNMatch} returns \var{True} if the filename in \var{Name}
-matches the wildcard pattern in \var{Pattern}, \var{False} otherwise.
-
-\var{Pattern} can contain the wildcards \var{*} (match zero or more 
-arbitrary characters) or \var{?} (match a single character).
-\Errors
-None.
-\SeeAlso
-\seef{FSearch}, \seef{FExpand}
-\end{function}
-
-\FPCexample{ex69}
-
-\begin{function}{FSearch}
-\Declaration
-Function FSearch (Path : pathstr;DirList : string) : Pathstr;
-\Description
- Searches in \var{DirList}, a colon separated list of directories,
-for a file named \var{Path}. It then returns a path to the found file.
-\Errors
-An empty string if no such file was found.
-\SeeAlso
-\seef{BaseName}, \seef{DirName}, \seef{FExpand}, \seef{FNMatch}
-\end{function}
-
-\FPCexample{ex46}
-
-\begin{procedurel}{FSplit}{LFsplit}
-\Declaration
-Procedure FSplit(const Path:PathStr; \\
-Var Dir:DirStr;Var Name:NameStr;Var Ext:ExtStr);
-\Description
-\var{FSplit} splits a full file name into 3 parts : A \var{Path}, a
-\var{Name} and an extension  (in \var{ext}). 
-The extension is taken to be all letters after the last dot (.).
-\Errors
-None.
-\SeeAlso
-\seef{FSearch}
-\end{procedurel}
-
-\FPCexample{ex67}
-
-\begin{function}{FSStat}
-\Declaration
-Function FSStat (Path : Pathstr; Var Info : statfs) : Boolean;
-Function FSStat (Fd:longint;Var Info:stat) : Boolean;
-\Description
- Return in \var{Info} information about the filesystem on which the file
-\var{Path} resides, or on which the file with file descriptor \var{fd}
-resides. 
-Info is of type \var{statfs}. The function returns \var{True} if the call 
-was succesfull, \var{False} if the call failed.
-\Errors
- \var{LinuxError} is used to report errors.
-\begin{description}
-\item[sys\_enotdir] A component of \var{Path} is not a directory.
-\item[sys\_einval] Invalid character in \var{Path}.
-\item[sys\_enoent] \var{Path} does not exist.
-\item[sys\_eaccess] Search permission is denied for  component in
-\var{Path}.
-\item[sys\_eloop] A circular symbolic link was encountered in \var{Path}.
-\item[sys\_eio] An error occurred while reading from the filesystem.
-\end{description}
-
-\SeeAlso
-\seef{FStat}, \seef{LStat}, \seem{statfs}{2}
-\end{function}
-
-\FPCexample{ex30}
-
-
-\begin{function}{FStat}
-\Declaration
-Function FStat(Path:Pathstr;Var Info:stat):Boolean;
-Function FStat(Fd:longint;Var Info:stat):Boolean;  
-Function FStat(var F:Text;Var Info:stat):Boolean;  
-Function FStat(var F:File;Var Info:stat):Boolean;  
-\Description
-\var{FStat} gets information about the file specified in one of the
-following:
-\begin{description}
-\item [Path] a file on the filesystem.
-\item [Fd] a valid file descriptor.
-\item [F] an opened text file or untyped file.
-\end{description}
-and stores it in  \var{Info}, which is of type \var{stat}.
-The function returns \var{True} if the call was succesfull, 
-\var{False} if the call failed.
-
-\Errors
- \var{LinuxError} is used to report errors.
-\begin{description}
-\item[sys\_enoent] \var{Path} does not exist.
-\end{description}
-\SeeAlso
-\seef{FSStat}, \seef{LStat}, \seem{stat}{2}
-\end{function}
-
-\FPCexample{ex28}
-
-\begin{function}{Fcntl}
-\Declaration
-Function  Fcntl(Fd:longint;Cmd:Integer):integer;
-Function  Fcntl(var Fd:Text;Cmd:Integer):integer;   
-\Description
-Read a file's attributes. \var{Fd} is an assigned file, or a valid file
-descriptor.
-\var{Cmd} speciefies what to do, and is one of the following:
-\begin{description}
-\item[F\_GetFd] Read the close\_on\_exec flag. If the low-order bit is 0, then
-the file will remain open across execve calls.
-\item[F\_GetFl] Read the descriptor's flags.
-\item[F\_GetOwn] Get the Process ID of the owner of a socket.
-\end{description}
-
-\Errors
-\var{LinuxError} is used to report errors.
-\begin{description}
-\item[sys\_ebadf] \var{Fd} has a bad file descriptor.
-\end{description}
-
-\SeeAlso
-\seep{Fcntl}, \seem{Fcntl}{2} 
-\end{function}
-
-\begin{procedure}{Fcntl}
-\Declaration
-Procedure Fcntl (Fd :  text, Cmd : Integer; Arg : longint);
-Procedure Fcntl (Fd:longint;Cmd:longint;Arg:Longint);
-\Description
-Read or Set a file's attributes. \var{Fd} is an assigned file or a
-valid file descriptor.
-\var{Cmd} speciefies what to do, and is one of the following:
-\begin{description}
-\item[F\_SetFd] Set the close\_on\_exec flag of \var{Fd}. (only the least
-siginificant bit is used).
-\item[F\_GetLk] Return the \var{flock} record that prevents this process from
-obtaining the lock, or set the \var{l\_type} field of the lock of there is no
-obstruction. Arg is a pointer to a flock record.
-\item[F\_SetLk] Set the lock or clear it (depending on \var{l\_type} in the
-\var{flock} structure). if the lock is held by another process, an error
-occurs.
-\item[F\_GetLkw] Same as for \textbf{F\_Setlk}, but wait until the lock is
-released.
-\item[F\_SetOwn] Set the Process or process group that owns a socket.
-\end{description}
-
-\Errors
-
-\var{LinuxError} is used to report errors.
-\begin{description}
-\item[sys\_ebadf] \var{Fd} has a bad file descriptor.
-\item[sys\_eagain or sys\_eaccess] For \textbf{F\_SetLk}, if the lock is
-held by another process.
-\end{description}
-
-\SeeAlso
-\seef{Fcntl}, \seem{Fcntl}{2}, seef{FLock}
-\end{procedure}
-
-\begin{function}{Fork}
-\Declaration
-Function Fork  : Longint;
-\Description
-Fork creates a child process which is a copy of the parent process.
-Fork returns the process ID in the parent process, and zero in the child's
-process. (you can get the parent's PID with \seef{GetPPid}).
-
-\Errors
-On error, -1 is returned to the parent, and no child is created.
-\begin{description}
-\item [sys\_eagain] Not enough memory to create child process.
-\end{description}
-\SeeAlso
-\seep{Execve}, \seef{Clone}, \seem{fork}{2}
-\end{function}
-
-\begin{function}{FRename}
-\Declaration
-Function  FReName (OldName,NewName : Pchar) : Boolean;
-Function  FReName (OldName,NewName : String) : Boolean;
-\Description
-\var{FRename} renames the file \var{OldName} to \var{NewName}. \var{NewName}
-can be in a different directory than \var{OldName}, but it cannot be on
-another partition (device). Any existing file on the new location will be replaced.
-
-If the operation fails, then the \var{OldName} file will be preserved. 
-
-The function returns \var{True} on succes, \var{False} on failure.
-\Errors
-On error, errors are reported in \var{LinuxError}. Possible errors include:
-\begin{description}
-\item[sys\_eisdir] \var{NewName} exists and is a directory, but \var{OldName}
-is not a directory.
-\item[sys\_exdev] \var{NewName} and \var{OldName} are on different devices.
-\item[sys\_enotempty or sys\_eexist] \var{NewName} is an existing, non-empty
-directory. 
-\item[sys\_ebusy] \var{OldName} or \var{NewName} is a directory and is in
-use by another process.
-\item[sys\_einval] \var{NewName} is part of \var{OldName}.
-\item[sys\_emlink] \var{OldPath} or \var{NewPath} already have tha maximum
-amount of links pointing to them.
-\item[sys\_enotdir] part of \var{OldName} or \var{NewName} is not
-directory.
-\item[sys\_efault] For the \var{pchar} case: One of the pointers points to
-an invalid address.
-\item[sys\_eaccess] access is denied when attempting to move the file.
-\item[sys\_enametoolong] Either \var{OldName} or \var{NewName} is too long.
-\item[sys\_enoent] a directory component in \var{OldName} or \var{NewName}
-didn't exist.
-\item[sys\_enomem] not enough kernel memory.
-\item[sys\_erofs] \var{NewName} or \var{OldName} is on a read-only file
-system.
-\item[sys\_eloop] too many symbolic links were encountered trying to expand
-\var{OldName} or \var{NewName}
-\item[sys\_enospc] the filesystem has no room for the new directory entry.
-\end{description}
-\SeeAlso
-\seef{UnLink}
-\end{function}
-
-
-\begin{procedure}{GetDate}
-\Declaration
-Procedure GetDate  (Var Year, Month, Day : Word) ;
-\Description
-Returns the current date.
-\Errors
-None
-\SeeAlso
-\seef{GetEpochTime}, \seep{GetTime},  \seep{GetDateTime}, \seep{EpochToLocal} 
-\end{procedure}
-
-\FPCexample{ex6}
-
-\begin{procedure}{GetDateTime}
-\Declaration
-Procedure GetDateTime(Var Year,Month,Day,hour,minute,second:Word);
-\Description
-Returns the current date and time. The time is corrected for the local time
-zone. This procedure is equivalent to the \seep{GetDate} and \var{GetTime}
-calls.
-\Errors
-None
-\SeeAlso
-\seef{GetEpochTime}, \seep{GetTime}, \seep{EpochToLocal}, \seep{GetDate} 
-\end{procedure}
-
-\FPCexample{ex60}
-
-\begin{function}{GetDomainName}
-\Declaration
-Function GetDomainName  : String;
-\Description
-Get the domain name of the machine on which the process is running.
-An empty string is returned if the domain is not set.
-
-\Errors
-None.
-\SeeAlso
- \seef{GetHostName},seem{Getdomainname}{2} 
-\end{function}
-
-\FPCexample{ex39}
-
-\begin{function}{GetEGid}
-\Declaration
-Function GetEGid  : Longint;
-\Description
- Get the effective group ID of the currently running process.
-\Errors
-None.
-\SeeAlso
-\seef{GetGid}, \seem{getegid}{2} 
-\end{function}
-
-\FPCexample{ex18}
-
-\begin{function}{GetEUid}
-\Declaration
-Function GetEUid  : Longint;
-\Description
- Get the effective user ID of the currently running process.
-\Errors
-None.
-\SeeAlso
-\seef{GetEUid}, \seem{geteuid}{2} 
-\end{function}
-
-\FPCexample{ex17}
-
-\begin{function}{GetEnv}
-\Declaration
-Function GetEnv (P : String) : PChar;
-\Description
-Returns the value of the environment variable in \var{P}. If the variable is
-not defined, nil is returned. The value of the environment variable may be
-the empty string.
-A PChar is returned to accomodate for strings longer than 255 bytes,
-\var{TERMCAP} and \var{LS\_COLORS}, for instance.
-
-\Errors
-None.
-\SeeAlso
-\seem{sh}{1}, \seem{csh}{1} 
-\end{function}
-
-\FPCexample{ex41}
-
-\begin{function}{GetEpochTime}
-\Declaration
-Function GetEpochTime  : longint;
-\Description
-returns the number of seconds since 00:00:00 gmt, january 1, 1970.
-it is adjusted to the local time zone, but not to DST.
-
-\Errors
-no errors
-\SeeAlso
-\seep{EpochToLocal}, \seep{GetTime}, \seem{time}{2}
-\end{function}
-
-\FPCexample{ex1}
-
-\begin{function}{GetFS}
-\Declaration
-Function GetFS (Var F : Any File Type) : Longint;
-\Description
-\var{GetFS} returns the file selector that the kernel provided for your
-file. In principle you don' need this file selector. Only for some calls
-it is needed, such as the \seef{Select} call or so.
-\Errors
-In case the file was not opened, then -1 is returned.
-\SeeAlso
-\seef{Select}
-\end{function}
-
-\FPCexample{ex34}
-
-\begin{function}{GetGid}
-\Declaration
-Function GetGid  : Longint;
-\Description
- Get the real group ID of the currently running process.
-\Errors
-None.
-\SeeAlso
-\seef{GetEGid}, \seem{getgid}{2} 
-\end{function}
-
-\FPCexample{ex18}
-
-\begin{function}{GetHostName}
-\Declaration
-Function GetHostName  : String;
-\Description
-Get the hostname of the machine on which the process is running.
-An empty string is returned if hostname is not set.
-
-\Errors
-None.
-\SeeAlso
- \seef{GetDomainName},seem{Gethostname}{2} 
-\end{function}
-
-\FPCexample{ex40}
-
-\begin{procedure}{GetLocalTimezone}
-\Declaration
-procedure GetLocalTimezone(timer:longint;var leap\_correct,leap\_hit:longint);
-procedure GetLocalTimezone(timer:longint);
-\Description
-\var{GetLocalTimeZone} returns the local timezone information. It also
-initializes the \var{TZSeconds} variable, which is used to correct the epoch time
-to local time. 
-
-There should never be any need to call this function directly. It is called by the
-initialization routines of the Linux unit.
-\SeeAlso
-\seef{GetTimezoneFile}, \seep{ReadTimezoneFile}
-\end{procedure}
-
-\begin{function}{GetPid}
-\Declaration
-Function GetPid  : Longint;
-\Description
- Get the Process ID of the currently running process.
-\Errors
-None.
-\SeeAlso
-\seef{GetPPid}, \seem{getpid}{2}
-\end{function}
-
-\FPCexample{ex16}
-
-\begin{function}{GetPPid}
-\Declaration
-Function GetPPid  : Longint;
-\Description
- Get the Process ID of the parent process.
-\Errors
-None.
-\SeeAlso
-\seef{GetPid}, \seem{getppid}{2}
-\end{function}
-
-\FPCexample{ex16}
-
-\begin{function}{GetPriority}
-\Declaration
-Function GetPriority (Which,Who : Integer) : Integer;
-\Description
-GetPriority returns the priority with which a process is running.
-Which process(es) is determined by the \var{Which} and \var{Who} variables.
-\var{Which} can be one of the pre-defined \var{Prio\_Process, Prio\_PGrp,
-Prio\_User}, in which case \var{Who} is the process ID, Process group ID or
-User ID, respectively.
-
-\Errors
-
- Error checking must be done on LinuxError, since a priority can be negative.
- \begin{description}
- \item[sys\_esrch] No process found using \var{which} and \var{who}.
- \item[sys\_einval] \var{Which} was not one of \var{Prio\_Process, Prio\_Grp
-or Prio\_User}.
- \end{description}
- 
-\SeeAlso
-\seef{SetPriority}, \seep{Nice}, \seem{Getpriority}{2}
-\end{function}
-For an example, see \seep{Nice}.
-
-\begin{procedure}{GetTime}
-\Declaration
-procedure GetTime(var hour,min,sec,msec,usec:word);
-procedure GetTime(var hour,min,sec,sec100:word);
-procedure GetTime(var hour,min,sec:word);
-\Description
-Returns the current time of the day, adjusted to local time.
-Upon return, the parameters are filled with
-\begin{description}
-\item[hour] Hours since 00:00 today.
-\item[min] minutes in current hour.
-\item[sec] seconds in current minute.
-\item[sec100] hundreds of seconds in current second.
-\item[msec] milliseconds in current second.
-\item[usec] microseconds in current second.
-\end{description}
-\Errors
-None
-\SeeAlso
-\seef{GetEpochTime}, \seep{GetDate}, \seep{GetDateTime}, \seep{EpochToLocal} 
-\end{procedure}
-
-\FPCexample{ex5}
-
-\begin{procedure}{GetTimeOfDay}
-\Declaration
-Procedure GetTimeOfDay(var tv:timeval);
-\Description
-\var{GetTimeOfDay} returns the number of seconds since 00:00, January 1 
-1970, GMT in a \var{timeval} record. This time NOT corrected any way, 
-not taking into account timezones, daylight savings time and so on.
-
-It is simply a wrapper to the kernel system call. To get the local time,
-\seep{GetTime}.
-\Errors
-None.
-\SeeAlso
-\seep{GetTime}, \seef{GetTimeOfDay}
-\end{procedure}
-
-\begin{function}{GetTimeOfDay}
-\Declaration
-Function GetTimeOfDay:longint;
-\Description
-\var{GetTimeOfDay} returns the number of seconds since 00:00, January 1
-1970, GMT. This time NOT corrected any way, not taking into account
-timezones, daylight savings time and so on.
-
-It is simply a wrapper to the kernel system call. To get the local time,
-\seep{GetTime}.
-\Errors
-None.
-\SeeAlso
-\seep{GetTimeOfDay}, \seep{GetTime}
-\end{function}
-
-\begin{function}{GetTimezoneFile}
-\Declaration
-function GetTimezoneFile:string;
-\Description
-\var{GetTimezoneFile} returns the location of the current timezone file.
-The location of file is determined as follows:
-\begin{enumerate}
-\item If \file{/etc/timezone} exists, it is read, and the contents of this
-file is returned. This should work on Debian systems.
-\item If \file{/usr/lib/zoneinfo/localtime} exists, then it is returned.
-(this file is a symlink to the timezone file on SuSE systems)
-\item If \file{/etc/localtime} exists, then it is returned. 
-(this file is a symlink to the timezone file on RedHat systems)
-\end{enumerate}
-\Errors
-If no file was found, an empty string is returned.
-\SeeAlso
-\seep{ReadTimezoneFile}
-\end{function}
-
-\begin{function}{GetUid}
-\Declaration
-Function GetUid  : Longint;
-\Description
- Get the real user ID of the currently running process.
-\Errors
-None.
-\SeeAlso
-\seef{GetEUid}, \seem{getuid}{2} 
-\end{function}
-
-\FPCexample{ex17}
-
-\begin{function}{Glob}
-\Declaration
-Function Glob (Const Path : Pathstr) : PGlob;
-\Description
-Glob returns a pointer to a glob structure which contains all filenames which
-exist and match the pattern in \var{Path}.
-The pattern can contain wildcard characters, which have their
-usual meaning.
-
-\Errors
- Returns nil on error, and \var{LinuxError} is set.
-\begin{description}
-\item[sys\_enomem] No memory on heap for glob structure.
-\item[others] As returned by the opendir call, and sys\_readdir.
-\end{description}
-
-\SeeAlso
-\seep{GlobFree}, \seem{Glob}{3} 
-\end{function}
-
-\FPCexample{ex49}
-
-\begin{procedure}{GlobFree}
-\Declaration
-Procedure GlobFree (Var P : Pglob);
-\Description
-Releases the memory, occupied by a pglob structure. \var{P} is set to nil.
-\Errors
-None
-\SeeAlso
- \seef{Glob} 
-\end{procedure}
-For an example, see \seef{Glob}.
-
-\begin{procedure}{IOCtl}
-\Declaration
-Procedure IOCtl (Handle,Ndx: Longint; Data: Pointer);
-\Description
-This is a general interface to the Unix/ \linux ioctl call.
-It performs various operations on the filedescriptor \var{Handle}.
-\var{Ndx} describes the operation to perform.
-\var{Data} points to data needed for the \var{Ndx} function. 
-The structure of this data is function-dependent, so we don't elaborate on
-this here. 
-For more information on this, see various manual pages under linux.
-
-\Errors
-
-Errors are reported in LinuxError. They are very dependent on the used
-function, that's why we don't list them here
-
-\SeeAlso
-\seem{ioctl}{2}
-\end{procedure}
-
-\FPCexample{ex54}
-
-\begin{function}{IOperm}
-\Declaration
-Function IOperm (From,Num : Cadinal; Value : Longint) : boolean;
-\Description
-\var{IOperm}
-  sets permissions on \var{Num} ports starting with port \var{From} to 
-  \var{Value}. The function returns \var{True} if the call was successfull,
-  \var{False} otherwise.
-{\em Remark:}
-\begin{itemize}
-\item This works ONLY as root.
-\item Only the first \var{0x03ff} ports can be set.
-\item When doing a \seef{Fork}, the permissions are reset. When doing a
-\seep{Execve} they are kept.
-\end{itemize}
-
-\Errors
-Errors are returned in \var{LinuxError}
-\SeeAlso
-\seem{ioperm}{2}
-\end{function}
-
-\begin{function}{IsATTY}
-\Declaration
-Function IsATTY (var f) : Boolean;
-\Description
-Check if the filehandle described by \var{f} is a terminal.
-f can be of type
-\begin{enumerate}
-\item \var{longint} for file handles;
-\item \var{Text} for \var{text} variables such as \var{input} etc.
-\end{enumerate}
-Returns \var{True} if \var{f} is a terminal, \var{False} otherwise.
-
-\Errors
-No errors are reported
-\SeeAlso
-\seep{IOCtl},\seef{TTYName}
-\end{function}
-\begin{functionl}{S\_ISBLK}{ISBLK}
-\Declaration
-Function S\_ISBLK (m:integer) : boolean;
-\Description
- \var{S\_ISBLK} checks the file mode \var{m} to see whether the file is a
-block device file. If so it returns \var{True}.
-
-\Errors
-\seef{FStat},
- \seefl{S\_ISLNK}{ISLNK}, 
- \seefl{S\_ISREG}{ISREG},
- \seefl{S\_ISDIR}{ISDIR},
- \seefl{S\_ISCHR}{ISCHR},
- \seefl{S\_ISFIFO}{ISFIFO},
- \seefl{S\_ISSOCK}{ISSOCK}
-
-\SeeAlso
-ISLNK.
-\end{functionl}
-\begin{functionl}{S\_ISCHR}{ISCHR}
-\Declaration
-Function S\_ISCHR (m:integer) : boolean;
-\Description
- \var{S\_ISCHR} checks the file mode \var{m} to see whether the file is a
-character device file. If so it returns \var{True}.
-
-\Errors
-\seef{FStat},
- \seefl{S\_ISLNK}{ISLNK}, 
- \seefl{S\_ISREG}{ISREG},
- \seefl{S\_ISDIR}{ISDIR},
- \seefl{S\_ISBLK}{ISBLK},
- \seefl{S\_ISFIFO}{ISFIFO},
- \seefl{S\_ISSOCK}{ISSOCK}
-
-\SeeAlso
-ISLNK.
-\end{functionl}
-\begin{functionl}{S\_ISDIR}{ISDIR}
-\Declaration
-Function S\_ISDIR (m:integer) : boolean;
-\Description
- \var{S\_ISDIR} checks the file mode \var{m} to see whether the file is a
-directory. If so it returns \var{True}
-
-\Errors
-\seef{FStat},
- \seefl{S\_ISLNK}{ISLNK}, 
- \seefl{S\_ISREG}{ISREG},
- \seefl{S\_ISCHR}{ISCHR},
- \seefl{S\_ISBLK}{ISBLK},
- \seefl{S\_ISFIFO}{ISFIFO},
- \seefl{S\_ISSOCK}{ISSOCK}
-
-\SeeAlso
-ISLNK.
-\end{functionl}
-\begin{functionl}{S\_ISFIFO}{ISFIFO}
-\Declaration
-Function S\_ISFIFO (m:integer) : boolean;
-\Description
- \var{S\_ISFIFO} checks the file mode \var{m} to see whether the file is a
-fifo (a named pipe). If so it returns \var{True}.
-
-\Errors
-\seef{FStat},
- \seefl{S\_ISLNK}{ISLNK}, 
- \seefl{S\_ISREG}{ISREG},
- \seefl{S\_ISDIR}{ISDIR},
- \seefl{S\_ISCHR}{ISCHR},
- \seefl{S\_ISBLK}{ISBLK},
- \seefl{S\_ISSOCK}{ISSOCK}
-
-\SeeAlso
-ISLNK.
-\end{functionl}
-
-\begin{functionl}{S\_ISLNK}{ISLNK}
-\Declaration
-Function S\_ISLNK (m:integer) : boolean;
-\Description
- \var{S\_ISLNK} checks the file mode \var{m} to see whether the file is a
-symbolic link. If so it returns \var{True}
-
-\Errors
-\seef{FStat},
- \seefl{S\_ISREG}{ISREG},
- \seefl{S\_ISDIR}{ISDIR},
- \seefl{S\_ISCHR}{ISCHR},
- \seefl{S\_ISBLK}{ISBLK},
- \seefl{S\_ISFIFO}{ISFIFO},
- \seefl{S\_ISSOCK}{ISSOCK}
-
-\SeeAlso
-\end{functionl}
-
-
-\FPCexample{ex53}
-
-\begin{functionl}{S\_ISREG}{ISREG}
-\Declaration
-Function S\_ISREG (m:integer) : boolean;
-\Description
- \var{S\_ISREG} checks the file mode \var{m} to see whether the file is a
-regular file. If so it returns \var{True}
-
-\Errors
-\seef{FStat},
- \seefl{S\_ISLNK}{ISLNK}, 
- \seefl{S\_ISDIR}{ISDIR},
- \seefl{S\_ISCHR}{ISCHR},
- \seefl{S\_ISBLK}{ISBLK},
- \seefl{S\_ISFIFO}{ISFIFO},
- \seefl{S\_ISSOCK}{ISSOCK}
-
-\SeeAlso
-ISLNK.
-\end{functionl}
-\begin{functionl}{S\_ISSOCK}{ISSOCK}
-\Declaration
-Function S\_ISSOCK (m:integer) : boolean;
-\Description
- \var{S\_ISSOCK} checks the file mode \var{m} to see whether the file is a
-socket. If so it returns \var{True}.
-
-\Errors
-\seef{FStat},
- \seefl{S\_ISLNK}{ISLNK}, 
- \seefl{S\_ISREG}{ISREG},
- \seefl{S\_ISDIR}{ISDIR},
- \seefl{S\_ISCHR}{ISCHR},
- \seefl{S\_ISBLK}{ISBLK},
- \seefl{S\_ISFIFO}{ISFIFO}
-
-\SeeAlso
-ISLNK.
-\end{functionl}
-
-\begin{function}{Kill}
-\Declaration
-Function Kill (Pid : Longint; Sig : Integer) : Integer;
-\Description
- Send a signal \var{Sig} to a process or process group. If \var{Pid}>0 then
-the signal is sent to \var{Pid}, if it equals -1, then the signal is sent to
-all processes except process 1. If \var{Pid}<-1 then the signal is sent to
-process group -Pid.
-The return value is zero, except in case three, where the return value is the
-number of processes to which the signal was sent.
-
-\Errors
-\var{LinuxError} is used to report errors:
-\begin{description}
-\item[sys\_einval] An invalid signal is sent.
-\item[sys\_esrch] The \var{Pid} or process group don't exist.
-\item[sys\_eperm] The effective userid of the current process doesn't math
-the one of process \var{Pid}.
-\end{description}
-
-\SeeAlso
-\seep{SigAction}, \seef{Signal}, \seem{Kill}{2} 
-\end{function}
-
-\begin{function}{LStat}
-\Declaration
-Function LStat (Path : Pathstr; Var Info : stat) : Boolean;
-\Description
-\var{LStat} gets information about the link specified in \var{Path}, and stores it in 
-\var{Info}, which is of type \var{stat}. Contrary to \var{FStat}, it stores
-information about the link, not about the file the link points to.
-The function returns \var{True} if the call was succesfull, \var{False} if the call
-failed.
-
-\Errors
- \var{LinuxError} is used to report errors.
-\begin{description}
-\item[sys\_enoent] \var{Path} does not exist.
-\end{description}
-
-\SeeAlso
-\seef{FStat}, \seef{FSStat}, \seem{stat}{2}
-\end{function}
-
-\FPCexample{ex29}
-
-\begin{function}{Link}
-\Declaration
-Function Link (OldPath,NewPath : pathstr) : Boolean;
-\Description
-\var{Link} makes \var{NewPath} point to the same file als \var{OldPath}. The two files
-then have the same inode number. This is known as a 'hard' link.
-The function returns \var{True} if the call was succesfull, \var{False} if the call
-failed.
-
-\Errors
- Errors are returned in \var{LinuxError}.
-\begin{description}
-\item[sys\_exdev] \var {OldPath} and \var {NewPath} are not on the same
-filesystem.
-\item[sys\_eperm] The filesystem containing oldpath and newpath doesn't
-support linking files.
-\item[sys\_eaccess] Write access for the directory containing \var{Newpath}
-is disallowed, or one of the directories in \var{OldPath} or {NewPath} has no
-search (=execute) permission.
-\item[sys\_enoent] A directory entry in \var{OldPath} or \var{NewPath} does
-not exist or is a symbolic link pointing to a non-existent directory.
-\item[sys\_enotdir] A directory entry in \var{OldPath} or \var{NewPath} is
-nor a directory.
-\item[sys\_enomem] Insufficient kernel memory.
-\item[sys\_erofs] The files are on a read-only filesystem.
-\item[sys\_eexist] \var{NewPath} already exists.
-\item[sys\_emlink] \var{OldPath} has reached maximal link count.
-\item[sys\_eloop] \var{OldPath} or \var{NewPath} has a reference to a circular
-symbolic link, i.e. a symbolic link, whose expansion points to itself.
-\item[sys\_enospc] The device containing \var{NewPath} has no room for anothe
-entry.
-\item[sys\_eperm] \var{OldPath} points to . or .. of a directory.
-\end{description}
-
-\SeeAlso
-\seef{SymLink}, \seef{UnLink}, \seem{Link}{2} 
-\end{function}
-
-\FPCexample{ex21}
-
-\begin{function}{LocalToEpoch}
-\Declaration
-Function LocalToEpoch (Year,Month,Day,Hour,Minute,Second : Word) : longint;
-\Description
-Converts the Local time to epoch time (=Number of seconds since 00:00:00 , January 1,
-1970 ).
-
-\Errors
-None
-\SeeAlso
-\seef{GetEpochTime}, \seep{EpochToLocal}, \seep{GetTime},\seep{GetDate} 
-\end{function}
-
-\FPCexample{ex4}
-
-\begin{function}{MkFifo}
-\Declaration
-Function MkFifo (PathName: String; Mode : Longint) : Boolean;
-\Description
-\var{MkFifo} creates named a named pipe in the filesystem, with name
-\var{PathName} and mode {Mode}. 
-
-\Errors
- \var{LinuxError} is used to report errors:
-\begin{description}
-\item[sys\_emfile] Too many file descriptors for this process.
-\item[sys\_enfile] The system file table is full.
-\end{description}
-
-\SeeAlso
-\seep{POpen}, \seef{MkFifo}, \seem{mkfifo}{4}
-\end{function}
-
-\begin{function}{MMap}
-\Declaration
-Function MMap(const m:tmmapargs):longint;
-\Description
-\var{MMap} maps or unmaps files or devices into memory. The different fields
-of the argument \var{m} determine what and how the \var{mmap} maps this:
-\begin{description}
-\item[address] Address where to mmap the device. This address is a hint, 
-and may not be followed.
-\item[size] Size (in bytes) of area to be mapped.
-\item[prot] Protection of mapped memory. This is a OR-ed combination of the
-following constants:
-\begin{description}
-\item[PROT\_EXEC] The memory can be executed.
-\item[PROT\_READ] The memory can be read.
-\item[PROT\_WRITE] The memory can be written.
-\item[PROT\_NONE] The memory can not be accessed.
-\end{description}
-\item[flags] Contains some options for the mmap call. It is an OR-ed
-combination of the following constants:
-\begin{description}
-\item[MAP\_FIXED] Do not map at another address than the given address. If the
-address cannot be used, \var{MMap} will fail.
-\item[MAP\_SHARED] Share this map with other processes that map this object.
-\item[MAP\_PRIVATE] Create a private map with copy-on-write semantics.
-\item[MAP\_ANONYMOUS] \var{fd} does not have to be a file descriptor.
-\end{description}
-One of the options \var{MAP\_SHARED} and \var{MAP\_PRIVATE} must be present,
-but not both at the same time.
-\item[fd] File descriptor from which to map.
-\item[offset] Offset to be used in file descriptor fd.
-\end{description}
-
-The function returns a pointer to the mapped memory, or a -1 in case of en
-error.
-\Errors
-On error, -1 is returned and LinuxError is set to the error code:
-\begin{description}
-\item[Sys\_EBADF] \var{fd} is not a valid file descriptor and 
-\var{MAP\_ANONYMOUS} was not specified.
-\item[Sys\_EACCES] \var{MAP\_PRIVATE} was specified, but fd is not open for 
-reading. Or \var{MAP\_SHARED} was asked and \var{PROT\_WRITE} is  set, fd 
-is not open for writing
-\item[Sys\_EINVAL] One of the record fields \var{Start}, \var{length} or 
-\var{offset} is invalid.
-\item[Sys\_ETXTBUSY] \var{MAP\_DENYWRITE} was set but the object specified  
-by fd is open for writing.
-\item[Sys\_EAGAIN] \var{fd} is locked, or too much memory is locked.
-\item[Sys\_ENOMEM] Not enough memory for this operation.
-\end{description}
-\SeeAlso
-\seef{MUnMap}, \seem{mmap}{2}
-\end{function}
-
-\FPCexample{ex66}
-
-\begin{function}{MUnMap}
-\Declaration
-function MUnMap (P : Pointer; Size : Longint) : Boolean;
-\Description
-\var{MUnMap} unmaps the memory block of size \var{Size}, pointed to by 
-\var{P}, which was previously allocated with \seef{MMap}.
-
-The function returns \var{True} if successful, \var{False} otherwise.
-\Errors
-In case of error the function returns \var{False} and \var{LinuxError}
-is set to an error value. See \seef{MMap} for possible error values.
-\SeeAlso
-\seef{MMap}, \seem{munmap}{2}
-\end{function}
-
-For an example, see \seef{MMap}.
-
-\begin{function}{NanoSleep}
-\Declaration
-Function NanoSleep(const req : timespec;var rem : timespec) : longint;
-\Description
-\var{NanoSleep} suspends the process till a time period as specified
-in \var{req} has passed. Then the function returns. If the
-call was interrupted (e.g. by some signal) then the function may
-return earlier, and \var{rem} will contain the remaining time till the
-end of the intended period. In this case the return value will be 
--1, and \var{LinuxError} will be set to \var{EINTR}
-
-If the function returns without error, the return value is zero.
-\Errors
-If the call was interrupted, -1 is returned, and \var{LinuxError} is set
-to \var{EINTR}. If invalid time values were specified, then -1 is returned
-and \var{LinuxError} is set to \var{EINVAL}.
-\SeeAlso
-\seep{Pause}, \seef{Alarm}
-\end{function}
-
-\FPCexample{ex70}
-
-\begin{procedure}{Nice}
-\Declaration
-Procedure Nice ( N : Integer);
-\Description
-\var{Nice} adds \var{-N} to the priority of the running process. The lower the
-priority numerically, the less the process is favored.
-Only the superuser can specify a negative \var{N}, i.e. increase the rate at
-which the process is run.
-
-\Errors
- Errors are returned in \var{LinuxError}
-\begin{description}
-\item [sys\_eperm] A non-superuser tried to specify a negative \var{N}, i.e.
-do a priority increase.
-\end{description}
-
-\SeeAlso
-\seef{GetPriority}, \seef{SetPriority}, \seem{Nice}{2}
-\end{procedure}
-
-\FPCexample{ex15}
-
-\begin{function}{Octal}
-\Declaration
-Function Octal(l:longint):longint;
-\Description
-\var{Octal} will convert a number specified as an octal number to it's
-decimal value.
-
-This is useful for the \seef{Chmod} call, where permissions are specified
-as octal numbers.
-\Errors
-No checking is performed whether the given number is a correct Octal number.
-e.g. specifying \var{998} is possible; the result will be wrong in that
-case.
-\SeeAlso
-\seef{Chmod}.
-\end{function}
-
-\FPCexample{ex68}
-
-\begin{function}{OpenDir}
-\Declaration
-Function OpenDir (f:pchar) : pdir;
-Function OpenDir (f:string) : pdir;
-\Description
- \var{OpenDir} opens the directory  \var{f}, and returns a \var{pdir}
-pointer to a \var{Dir} record, which can be used to read the directory 
-structure. If the directory cannot be opened, \var{nil} is returned.
-\Errors
-Errors are returned in LinuxError.
-\SeeAlso
-\seef{CloseDir}, \seef{ReadDir}, \seep{SeekDir}, \seef{TellDir},
-\seem{opendir}{3}
-\end{function}
-
-
-\FPCexample{ex35}
-
-
-\begin{procedure}{pause}
-\Declaration
-Procedure Pause;
-\Description
-\var{Pause} puts the process to sleep and waits until the application 
-receives  a signal. If a signal handler is installed for the received 
-sigal, the handler will be called and after that pause will return 
-control to the process.
-\Errors
-None.
-\end{procedure}
-
-For an example, see \seef{Alarm}.
-
-
-\begin{function}{PClose}
-\Declaration
-Function PClose (Var F : FileType) : longint;
-\Description
- \var{PClose} closes a file opened with \var{POpen}. It waits for the
-command to complete, and then returns the exit status of the command. 
-
-\Errors
-\var{LinuxError} is used to report errors. If it is different from zero,
-the exit status is not valid.
-\SeeAlso
-\seep{POpen}
-\end{function}
-For an example, see \seep{POpen}
-
-\begin{procedure}{POpen}
-\Declaration
-Procedure POpen (Var F : FileType; Cmd : pathstr; rw : char);
-\Description
- Popen runs the command specified in \var{Cmd},
- and redirects the standard in or output of the
-command to the other end of the pipe \var{F}. The parameter \var{rw}
-indicates the direction of the pipe. If it is set to \var{'W'}, then F can
-be used to write data, which will then be read by the command from stdinput.
-If it is set to \var{'R'}, then the standard output of the command can be 
-read from \var{F}. \var{F} should be reset or rewritten prior to using it.
-\var{F} can be of type \var{Text} or \var{File}.
-A file opened with \var {POpen} can be closed with \var{Close}, but also
-with \seef{PClose}. The result is the same, but \var{PClose} returns the
-exit status of the command \var{Cmd}.
-\Errors
-Errors are reported in \var{LinuxError} and are essentially those of the
-Execve, Dup and AssignPipe commands.
-
-\SeeAlso
-\seef{AssignPipe}, \seem{popen}{3}, \seef{PClose}
-\end{procedure}
-
-\FPCexample{ex37}
-
-\begin{function}{ReadDir}
-\Declaration
-Function ReadDir (p:pdir) : pdirent;
-\Description
-\var{ReadDir} reads the next entry in the directory pointed to by \var{p}.
-It returns a \var{pdirent} pointer to a structure describing the entry.
-If the next entry can't be read, \var{Nil} is returned.
-
-\Errors
-Errors are returned in LinuxError.
-\SeeAlso
-\seef{CloseDir}, \seef{OpenDir}, \seep{SeekDir}, \seef{TellDir},
-\seem{readdir}{3}
-\end{function}
-
-For an example, see \seef{OpenDir}.
-
-\begin{function}{ReadLink}
-\Declaration
-Function  ReadLink(name,linkname:pchar;maxlen:longint):longint;
-Function  ReadLink(name:pathstr):pathstr;
-\Description
-\var{ReadLink} returns the file the symbolic link \var{name} is pointing 
-to. The first form of this function accepts a buffer \var{linkname} of
-length \var{maxlen} where the filename will be stored. It returns the
-actual number of characters stored in the buffer.
-
-The second form of the function returns simply the name of the file.
-\Errors
-On error, the first form of the function returns -1; the second one returns
-an empty string. \var{LinuxError} is set to report errors:
-\begin{description}
-\item[SYS\_ENOTDIR] A part of the path in \var{Name} is not a directory.
-\item[SYS\_EINVAL] maxlen is not positive, or the  file is not a symbolic link.
-\item[SYS\_ENAMETOOLONG] A pathname, or a component of a pathname,  was  too
-long.
-\item[SYS\_ENOENT] the link \var{name} does not exist.
-\item[SYS\_EACCES] No permission to search a directory in the path
-\item[SYS\_ELOOP]  Too many symbolic links were encountered in  trans­
-             lating the pathname.
-\item[SYS\_EIO] An  I/O  error occurred while reading from the file
-              system.
-\item[SYS\_EFAULT] The buffer is not part of the the process's memory space.
-\item[SYS\_ENOMEM] Not enough kernel memory was available.
-\end{description}
-\SeeAlso
-\seef{SymLink}
-\end{function}
-
-\FPCexample{ex62}
-
-\begin{procedure}{ReadPort}
-\Declaration
-Procedure ReadPort (Port : Longint; Var Value : Byte);
-Procedure ReadPort (Port : Longint; Var Value : Word);
-Procedure ReadPort (Port : Longint; Var Value : Longint);
-\Description
-\var{ReadPort} reads one Byte, Word or Longint from port \var{Port} into
-\var{Value}.
-
-Note that you need permission to read a port. This permission can be set by 
-the root user with the \seef{IOperm} call.
-\Errors
-In case of an error (not enough permissions read this port), runtime 216 
-({\em Access Violation}) will occur.
-\SeeAlso
-
-\seef{IOperm}, \seep{ReadPortB}, \seep{ReadPortW}, \seep{ReadPortL},\seep{WritePort},
-\seep{WritePortB}, \seep{WritePortL}, \seep{WritePortW}
-\end{procedure}
-
-\begin{procedure}{ReadPortB}
-\Declaration
-Procedure ReadPortB (Port : Longint; Var Buf; Count: longint);
-Function  ReadPortB (Port : Longint): Byte;
-\Description
-The procedural form of \var{ReadPortB} reads \var{Count} bytes from port
-\var{Port} and stores them in \var{Buf}. There must be enough memory
-allocated at \var{Buf} to store \var{Count} bytes.
-
-The functional form of \var{ReadPortB} reads 1 byte from port \var{B}
-and returns the byte that was read.
-
-Note that you need permission to read a port. This permission can be set by 
-the root user with the \seef{IOperm} call.
-
-\Errors
-In case of an error (not enough permissions read this port), runtime 216 
-({\em Access Violation}) will occur.
-
-\SeeAlso
-\seef{IOperm}, \seep{ReadPort}, \seep{ReadPortW}, \seep{ReadPortL},\seep{WritePort},
-\seep{WritePortB}, \seep{WritePortL}, \seep{WritePortW}
-\end{procedure}
-
-\begin{procedure}{ReadPortL}
-\Declaration
-function  ReadPortL (Port : Longint): LongInt;
-Procedure ReadPortL (Port : Longint; Var Buf; Count: longint);
-\Description
-The procedural form of \var{ReadPortL} reads \var{Count} longints from port
-\var{Port} and stores them in \var{Buf}. There must be enough memory
-allocated at \var{Buf} to store \var{Count} Longints.
-
-The functional form of \var{ReadPortB} reads 1 longint from port \var{B}
-and returns the longint that was read.
-
-Note that you need permission to read a port. This permission can be set by 
-the root user with the \seef{IOperm} call.
-\Errors
-In case of an error (not enough permissions read this port), runtime 216 
-({\em Access Violation}) will occur.
-\SeeAlso
-\seef{IOperm}, \seep{ReadPort}, \seep{ReadPortW}, \seep{ReadPortB},\seep{WritePort},
-\seep{WritePortB}, \seep{WritePortL}, \seep{WritePortW}
-\end{procedure}
-
-\begin{procedure}{ReadPortW}
-\Declaration
-Procedure ReadPortW (Port : Longint; Var Buf; Count: longint);
-function  ReadPortW (Port : Longint): Word;
-\Description
-The procedural form of \var{ReadPortB} reads \var{Count} words from port
-\var{Port} and stores them in \var{Buf}. There must be enough memory
-allocated at \var{Buf} to store \var{Count} words.
-
-The functional form of \var{ReadPortB} reads 1 word from port \var{B}
-and returns the word that was read.
-
-Note that you need permission to read a port. This permission can be set by 
-the root user with the \seef{IOperm} call.
-\Errors
-In case of an error (not enough permissions read this port), runtime 216 
-({\em Access Violation}) will occur.
-\SeeAlso
-\seef{IOperm}, \seep{ReadPort}, \seep{ReadPortB}, \seep{ReadPortL},\seep{WritePort},
-\seep{WritePortB}, \seep{WritePortL}, \seep{WritePortW}
-\end{procedure}
-
-
-\begin{procedure}{ReadTimezoneFile}
-\Declaration
-procedure ReadTimezoneFile(fn:string);
-\Description
-\var{ReadTimeZoneFile} reads the timezone file \var{fn} and initializes
-the local time routines based on the information found there.
-
-There should be no need to call this function. The initialization routines
-of the \file{linux} unit call this routine at unit startup.
-\Errors 
-None.
-\SeeAlso
-\seef{GetTimezoneFile}, \seep{GetLocalTimezone}
-\end{procedure}
-
-
-\begin{procedure}{SeekDir}
-\Declaration
-Procedure SeekDir (p:pdir;off:longint);
-\Description
- \var{SeekDir} sets the directory pointer to the \var{off}-th entry in the
-directory structure pointed to by \var{p}.
-\Errors
-Errors are returned in LinuxError.
-\SeeAlso
-\seef{CloseDir}, \seef{ReadDir}, \seef{OpenDir}, \seef{TellDir},
-\seem{seekdir}{3}
-\end{procedure}
-For an example, see \seef{OpenDir}.
-
-\begin{function}{Select}
-\Declaration
-Function Select (N : Longint; \\ var readfds,writefds,exceptfds : PFDset;
-Var Timeout) : Longint;
-\Description
-\var{Select} checks one of the file descriptors in the \var{FDSets} to see if its
-status changed.
-\var{readfds, writefds} and \var{exceptfds} are pointers to arrays of 256
-bits. If you want a file descriptor to be checked, you set the
-corresponding element in the array to 1. The other elements in the array
-must be set to zero. Three arrays are passed : The entries in \var{readfds}
-are checked to see if characters become available for reading. The entries
-in \var{writefds} are checked to see if it is OK to write to them, while
-entries in \var{exceptfds} are cheked to see if an exception occorred on
-them.
-You can use the functions \seepl{FD\_ZERO}{FDZero}, \seepl{FD\_Clr}{FDClr}, 
-\seepl{FD\_Set}{FDSet}, \seefl{FD\_IsSet}{FDIsSet} to manipulate the individual elements of a set.
-The pointers can be nil.
-\var{N} is the largest index of a nonzero entry plus 1. (= the largest
-file-descriptor + 1).
-\var{TimeOut} can be used to set a time limit. 
-If \var{TimeOut} can be two types :
-\begin{enumerate}
-\item \var{TimeOut} is of type \var{PTime} and contains a
-zero time, the call returns immediately. If \var{TimeOut} is \var{Nil}, the
-kernel will wait forever, or until a status changed.    
-\item \var{TimeOut} is of type \var{Longint}. If it is -1, this has the same
-effect as a \var{Timeout} of type  \var{PTime} which is \var{Nil}.
-Otherwise, \var{TimeOut} contains a time in milliseconds.
-\end{enumerate}
- 
-When the TimeOut is reached, or one of the file descriptors has changed,
-the \var{Select} call returns. On return, it will have modified the entries
-in the array which have actually changed, and it returns the number of
-entries that have been changed. If the timout was reached, and no decsriptor
-changed, zero is returned; The arrays of indexes are undefined after that.
-On error, -1 is returned.
-\Errors
-On error, the function returns -1, and Errors are reported in LinuxError :
-\begin{description}
-\item[SYS\_EBADF\ ] An invalid descriptot was specified in one of the sets.
-\item[SYS\_EINTR\ ] A non blocked signal was caught.
-\item[SYS\_EINVAL\ ]  \var{N} is negative or too big.
-\item[SYS\_ENOMEM\ ] \var{Select} was unable to allocate memory for its 
- internal tables.
-\end{description}
-\SeeAlso
-\seef{SelectText}, \seef{GetFS}, 
-\seepl{FD\_ZERO}{FDZero},
-\seepl{FD\_Clr}{FDClr},
-\seepl{FD\_Set}{FDSet}, 
-\seefl{FD\_IsSet}{FDIsSet}
-\end{function}
-
-\FPCexample{ex33}
-
-\begin{function}{SelectText}
-\Declaration
-Function SelectText ( var T : Text; TimeOut :PTime) : Longint;
-\Description
-\var{SelectText} executes the \seef{Select} call on a file of type
-\var{Text}. You can specify a timeout in \var{TimeOut}. The SelectText call
-determines itself whether it should check for read or write, depending on
-how the file was opened : With \var{Reset} it is checked for reading, with
-\var{Rewrite} and \var{Append} it is checked for writing.
-\Errors
-See \seef{Select}. \var{SYS\_EBADF} can also mean that the file wasn't
-opened.
-\SeeAlso
-\seef{Select}, \seef{GetFS}
-\end{function}
-
-\begin{function}{SetPriority}
-\Declaration
-Function SetPriority (Which,Who,Prio : Integer) : Integer;
-\Description
-SetPriority sets the priority with which a process is running.
-Which process(es) is determined by the \var{Which} and \var{Who} variables.
-\var{Which} can be one of the pre-defined \var{Prio\_Process, Prio\_PGrp,
-Prio\_User}, in which case \var{Who} is the process ID, Process group ID or
-User ID, respectively.
-\var{Prio} is a value in the range -20 to 20.
-
-\Errors
-
- Error checking must be done on LinuxError, since a priority can be negative.
- \begin{description}
- \item[sys\_esrch] No process found using \var{which} and \var{who}.
- \item[sys\_einval] \var{Which} was not one of \var{Prio\_Process, Prio\_Grp
-or Prio\_User}.
- \item[sys\_eperm] A process was found, but neither its effective or real
- user ID match the effective user ID of the caller.
- \item [sys\_eacces] A non-superuser tried to a priority increase.
- \end{description}
- 
-\SeeAlso
-\seef{GetPriority}, \seep{Nice}, \seem{Setpriority}{2}
-\end{function}
-For an example, see \seep{Nice}.
-
-\begin{function}{Shell}
-\Declaration
-Function Shell (Command : String) : Longint;
-\Description
-\var{Shell} invokes the bash shell (\file{/bin/sh}), and feeds it the
-command \var{Command} (using the \var{-c} option). The function then waits
-for the command to complete, and then returns the exit
-status of the command, or 127 if it could not complete the \seef{Fork} 
-or \seep{Execve} calls.
-
-\Errors
-Errors are reported in LinuxError.
-\SeeAlso
-\seep{POpen}, \seef{Fork}, \seep{Execve}, \seem{system}{3}
-\end{function}
-
-\FPCexample{ex56}
-
-\begin{procedure}{SigAction}
-\Declaration
-Procedure SigAction (Signum : Integer; Var Act,OldAct : PSigActionRec);
-\Description
- Changes the action to take upon receipt of a signal. \var{Act} and
-\var{Oldact} are pointers to a \var{SigActionRec} record.
-\var{SigNum} specifies the signal, and can be any signal except
-\textbf{SIGKILL} or \textbf{SIGSTOP}.
-If \var{Act} is non-nil, then the new action for signal \var{SigNum} is taken
-from it. If \var{OldAct} is non-nil, the old action is stored there.
-\var{Sa\_Handler} may be \var{SIG\_DFL} for the default action or
-\var{SIG\_IGN} to ignore the signal.
-\var{Sa\_Mask} Specifies which signals should be ignord during the execution
-of the signal handler.
-\var{Sa\_Flags} Speciefies a series of flags which modify the behaviour of
-the signal handler. You can 'or' none or more of the following :
-\begin{description}
-\item[SA\_NOCLDSTOP] If signum is \textbf{SIGCHLD} do not receive
-notification when child processes stop.
-\item[SA\_ONESHOT or SA\_RESETHAND] Restore the signal action to the default
-state once the signal handler has been called.
-\item[SA\_RESTART] For compatibility with BSD signals.
-\item[SA\_NOMASK or SA\_NODEFER] Do not prevent the signal from being received
-from within its own signal handler.
-\end{description}
-
-\Errors
-\var{LinuxError} is used to report errors.
-\begin{description}
-\item[sys\_einval] an invalid signal was specified, or it was
-\textbf{SIGKILL} or \textbf{SIGSTOP}.
-\item[sys\_efault] \var{Act,OldAct} point outside this process address space
-\item[sys\_eintr] System call was interrupted.
-\end{description}
-
-\SeeAlso
-
-\seep{SigProcMask}, \seef{SigPending}, \seep{SigSuspend}, \seef{Kill},
-\seem{Sigaction}{2}
-
-\end{procedure}
-
-\FPCexample{ex57}
-
-\begin{function}{SigPending}
-\Declaration
-Function SigPending  : SigSet;
-\Description
-Sigpending allows the examination of pending signals (which have been raised
-while blocked.) The signal mask of pending signals is returned.
-
-\Errors
-None
-\SeeAlso
-\seep{SigAction}, \seep{SigProcMask}, \seep{SigSuspend}, \seef{Signal},
-\seef{Kill}, \seem{Sigpending}{2} 
-\end{function}
-
-\begin{procedure}{SigProcMask}
-\Declaration
-Procedure SigProcMask (How : Integer; SSet,OldSSet : PSigSet);
-\Description
-Changes the list of currently blocked signals. The behaviour of the call
-depends on \var{How} :
-\begin{description}
-\item[SIG\_BLOCK] The set of blocked signals is the union of the current set
-and the \var{SSet} argument.
-\item[SIG\_UNBLOCK] The signals in \var{SSet} are removed from the set of
-currently blocked signals.
-\item[SIG\_SETMASK] The list of blocked signals is set so \var{SSet}.
-\end{description}
-If \var{OldSSet} is non-nil, then the old set is stored in it.
-
-\Errors
-\var{LinuxError} is used to report errors.
-\begin{description}
-\item[sys\_efault] \var{SSet} or \var{OldSSet} point to an adress outside
-the range of the process.
-\item[sys\_eintr] System call was interrupted.
-\end{description}
-
-\SeeAlso
-\seep{SigAction}, \seef{SigPending}, \seep{SigSuspend}, \seef{Kill},
-\seem{Sigprocmask}{2} 
-\end{procedure}
-
-\begin{procedure}{SigRaise}
-\Declaration
-Procedure SigRaise(Sig:integer);
-\Description
-\var{SigRaise} sends a \var{Sig} signal to the current process.
-\Errors
-None.
-\SeeAlso
-\seef{Kill}, \seef{GetPid}
-\end{procedure}
-
-\FPCexample{ex65}
-
-\begin{procedure}{SigSuspend}
-\Declaration
-Procedure SigSuspend (Mask : SigSet);
-\Description
-SigSuspend temporarily replaces the signal mask for the process with the one
-given in \var{Mask}, and then suspends the process until a signal is received.
-
-\Errors
-None
-\SeeAlso
-\seep{SigAction}, \seep{SigProcMask}, \seef{SigPending}, \seef{Signal},
-\seef{Kill}, \seem{SigSuspend}{2} 
-\end{procedure}
-
-\begin{function}{Signal}
-\Declaration
-Function Signal (SigNum : Integer; Handler : SignalHandler) : SignalHandler;
-\Description
-Signal installs a new signal handler for signal \var{SigNum}. This call has
-the same functionality as the \textbf{SigAction} call.
-The return value for Signal is the old signal handler, or nil on error.
-
-\Errors
-\var {LinuxError} is used to report errors :
-\begin{description}
-\item[SIG\_ERR] An error occurred.
-\end{description}
-
-\SeeAlso
-\seep{SigAction},\seef{Kill}, \seem{Signal}{2} 
-\end{function}
-
-\FPCexample{ex58}
-
-\begin{function}{StringToPPchar}
-\Declaration
-Function StringToPPChar(Var S:STring):ppchar;
-\Description
-\var{StringToPPChar} splits the string \var{S} in words, replacing any
-whitespace with zero characters. It returns a pointer to an array of pchars
-that point to the first letters of the words in S. This array is terminated
-by a \var{Nil} pointer.
-
-The function does {\em not} add a zero character to the end of the string
-unless it ends on whitespace.
-
-The function reserves memory on the heap to store the array of \var{PChar};
-The caller is responsible for freeing this memory. 
-
-This function can be called to create arguments for the various \var{Exec}
-calls.
-\Errors
-None.
-\SeeAlso
-\seef{CreateShellArgV}, \seep{Execve}, \seep{Execv}
-\end{function}
-
-\FPCexample{ex70}
-
-\begin{function}{SymLink}
-\Declaration
-Function SymLink (OldPath,NewPath : pathstr) : Boolean;
-\Description
-\var{SymLink} makes \var{Newpath} point to the file in \var{OldPath}, which doesn't
-necessarily exist. The two files DO NOT have the same inode number.
-This is known as a 'soft' link.
-The permissions of the link are irrelevant, as they are not used when
-following the link. Ownership of the file is only checked in case of removal
-or renaming of the link.
-The function returns \var{True} if the call was succesfull, \var{False} if the call
-failed.
-
-\Errors
- Errors are returned in \var{LinuxError}.
-\begin{description}
-\item[sys\_eperm] The filesystem containing oldpath and newpath doesn't
-support linking files.
-\item[sys\_eaccess] Write access for the directory containing \var{Newpath}
-is disallowed, or one of the directories in \var{OldPath} or {NewPath} has no
-search (=execute) permission.
-\item[sys\_enoent] A directory entry in \var{OldPath} or \var{NewPath} does
-not exist or is a symbolic link pointing to a non-existent directory.
-\item[sys\_enotdir] A directory entry in \var{OldPath} or \var{NewPath} is
-nor a directory.
-\item[sys\_enomem] Insufficient kernel memory.
-\item[sys\_erofs] The files are on a read-only filesystem.
-\item[sys\_eexist] \var{NewPath} already exists.
-\item[sys\_eloop] \var{OldPath} or \var{NewPath} has a reference to a circular
-symbolic link, i.e. a symbolic link, whose expansion points to itself.
-\item[sys\_enospc] The device containing \var{NewPath} has no room for anothe
-entry.
-\end{description}
-\SeeAlso
-\seef{Link}, \seef{UnLink}, \seef{ReadLink}, \seem{Symlink}{2} 
-\end{function}
-
-\FPCexample{ex22}
-
-\begin{function}{SysInfo}
-\Declaration
-Function  SysInfo(var Info:TSysinfo):Boolean;
-\Description
-\var{SysInfo} returns system information in \var{Info}. Returned information
-in \var{Info} includes:
-\begin{description}
-\item[uptime] Number of seconds since boot.
-\item[loads]  1, 5 and 15 minute load averages.
-\item[totalram] total amount of main memory.
-\item[freeram] amount of free memory.
-\item[sharedram] amount of shared memory
-\item[bufferram] amount of memory used by buffers.
-\item[totalswap] total amount of swapspace.
-\item[freeswap] amount of free swapspace.
-\item[procs] number of current processes.
-\end{description}
-\Errors
-None.
-\SeeAlso
-\seep{Uname}
-\end{function}
-
-\FPCexample{ex64}
-
-\begin{function}{TCDrain}
-\Declaration
-Function TCDrain (Fd:longint) : Boolean;
-\Description
- \var{TCDrain}
-  waits until all data to file descriptor \var{Fd} is transmitted.
-  
-  The function returns \var{True} if the call was succesfull, \var{False}
-  otherwise.
-
-\Errors
-Errors are reported in LinuxError
-\SeeAlso
-\seem{termios}{2}
-\end{function}
-
-\begin{function}{TCFlow}
-\Declaration
-Function TCFlow (Fd,Act:longint) : Boolean;
-\Description
- \var{TCFlow}
-  suspends/resumes transmission or reception of data to or from the file
-descriptor \var{Fd}, depending
-  on the action \var {Act}. This can be one of the following pre-defined
-values: 
-\begin{description}
-\item [TCOOFF\ ] suspend reception/transmission,
-\item [TCOON\ ] resume  reception/transmission,
-\item [TCIOFF\ ] transmit a stop character to stop input from the terminal, 
-\item [TCION\ ] transmit start to resume input from the terminal.
-\end{description}
-The function returns \var{True} if the call was succesfull, \var{False}
-otherwise.
-
-\Errors
-Errors are reported in LinuxError.
-\SeeAlso
-\seem{termios}{2}
-\end{function}
-
-\begin{function}{TCFlush}
-\Declaration
-Function TCFlush (Fd,QSel:longint) : Boolean;
-\Description
- \var{TCFlush}
-  discards all data sent or received to/from file descriptor \var{fd}. 
- \var{QSel} indicates which queue
-  should be discard. It can be one of the following pre-defined values :
-\begin{description}
-\item [TCIFLUSH\ ] input,
-\item [TCOFLUSH\ ] output,
-\item [TCIOFLUSH\ ] both input and output.
-\end{description}
-The function returns \var{True} if the call was succesfull, \var{False}
-otherwise.
-
-\Errors
-Errors are reported in LinuxError.
-\SeeAlso
-\seem{termios}{2}
-\end{function}
-
-\begin{function}{TCGetAttr}
-\Declaration
-Function TCGetAttr (fd:longint;var tios:TermIOS) : Boolean;
-\Description
- \var{TCGetAttr}
-  gets the terminal parameters from the terminal referred to by the file
-  descriptor \var{fd} and returns them in a \var{TermIOS} structure \var{tios}. 
-The function returns \var{True} if the call was succesfull, \var{False}
-otherwise.
-
-\Errors
-Errors are reported in LinuxError
-\SeeAlso
-\seef{TCSetAttr}, \seem{termios}{2} 
-\end{function}
-
-\FPCexample{ex55}
-
-\begin{function}{TCGetPGrp}
-\Declaration
-Function TCGetPGrp (Fd:longint;var Id:longint) : boolean;
-\Description
- \var{TCGetPGrp}
-  returns the process group ID of a foreground process group in \var{Id} 
-  The function returns \var{True} if the call was succesfull, \var{False}
-  otherwise
-
-\Errors
-Errors are reported in LinuxError
-\SeeAlso
-\seem{termios}{2}
-\end{function}
-
-\begin{function}{TCSendBreak}
-\Declaration
-Function TCSendBreak (Fd,Duration:longint) : Boolean;
-\Description
- \var{TCSendBreak} 
-  Sends zero-valued bits on an asynchrone serial connection decsribed by
-  file-descriptor \var{Fd}, for duration \var{Duration}.
-  The function returns \var{True} if the action was performed successfully,
-\var{False} otherwise.
-
-\Errors
-Errors are reported in LinuxError.
-\SeeAlso
-\seem{termios}{2}
-\end{function}
-
-\begin{function}{TCSetAttr}
-\Declaration
-Function TCSetAttr (Fd:longint;OptAct:longint;var Tios:TermIOS) : Boolean;
-\Description
- \var{TCSetAttr}
-  Sets the terminal parameters you specify in a \var{TermIOS} structure
-\var{Tios} for the terminal
-  referred to by the file descriptor \var{Fd}. \var{OptAct} specifies an 
-  optional action when the set need to be done,
-  this could be one of the following pre-defined values:
- \begin{description}
-\item [TCSANOW\ ] set immediately.
-\item [TCSADRAIN\ ] wait for output.
-\item [TCSAFLUSH\ ] wait for output and discard all input not yet read. 
-\end{description}
-The function Returns \var{True} if the call was succesfull, \var{False} 
-otherwise.
-
-\Errors
-Errors are reported in LinuxError.
-\SeeAlso
-\seef{TCGetAttr}, \seem{termios}{2}
-\end{function}
-For an example, see \seef{TCGetAttr}.
-
-\begin{function}{TCSetPGrp}
-\Declaration
-Function TCSetPGrp (Fd,Id:longint) : boolean;
-\Description
- \var{TCSetPGrp} Sets the Process Group Id to \var{Id}. 
-The function returns \var{True} if the call was successful, \var{False}
-otherwise.
-
-\Errors
-Errors are returned in LinuxError.
-\SeeAlso
-\seef{TCGetPGrp}, \seem{termios}{2}
-\end{function}
-For an example, see \seef{TCGetPGrp}.
-
-\begin{function}{TTYName}
-\Declaration
-Function TTYName (var f) : String;
-\Description
-Returns the name of the terminal pointed to by \var{f}. \var{f}
-must be a terminal. \var{f} can be of type:
-\begin{enumerate}
-\item \var{longint} for file handles;
-\item \var{Text} for \var{text} variables such as \var{input} etc.
-\end{enumerate}
-
-\Errors
- Returns an empty string in case of an error. \var{Linuxerror} may be set
- to indicate what error occurred, but this is uncertain.
-\SeeAlso
-\seef{IsATTY},\seep{IOCtl}
-\end{function}
-
-\begin{function}{TellDir}
-\Declaration
-Function TellDir (p:pdir) : longint;
-\Description
- \var{TellDir} returns the current location in the directory structure
-pointed to by \var{p}. It returns -1 on failure.
-\Errors
-Errors are returned in LinuxError.
-\SeeAlso
-\seef{CloseDir}, \seef{ReadDir}, \seep{SeekDir}, \seef{OpenDir},
-\seem{telldir}{3}
-\end{function}
-For an example, see \seef{OpenDir}.
-
-\begin{function}{Umask}
-\Declaration
-Function Umask (Mask : Integer) : Integer;
-\Description
-Change the file creation mask for the current user to \var{Mask}. The
-current mask is returned.
-
-\Errors
-None
-\SeeAlso
-\seef{Chmod}, \seem{Umask}{2}
-\end{function}
-
-\FPCexample{ex27}
-
-\begin{procedure}{Uname}
-\Declaration
-Procedure Uname (var unamerec:utsname);
-\Description
-\var{Uname} gets the name and configuration of the current \linux kernel,
-and returns it in \var{unamerec}.
-
-\Errors
-\var{LinuxError} is used to report errors.
-\SeeAlso
-\seef{GetHostName}, \seef{GetDomainName}, \seem{uname}{2}
-\end{procedure}
-
-\begin{function}{UnLink}
-\Declaration
-Function UnLink (Var Path) : Boolean;
-\Description
-\var{UnLink} decreases the link count on file \var{Path}. \var{Path} can be
-of type \var{PathStr} or \var{PChar}. If the link count is zero, the
-file is removed from the disk.
-The function returns \var{True} if the call was succesfull, \var{False} if the call
-failed.
-
-\Errors
- Errors are returned in \var{LinuxError}.
-\begin{description}
-\item[sys\_eaccess] You have no write access right in the directory
-containing \var{Path}, or you have no search permission in one of the
-directory components of \var{Path}.
-\item[sys\_eperm] The  directory containing pathname has the sticky-bit 
-set and the process's effective  uid is neither the uid of the 
-file to be deleted nor that of the directory containing it.
-\item[sys\_enoent] A component of the path doesn't exist.
-\item[sys\_enotdir] A directory component of the path is not a directory.
-\item[sys\_eisdir] \var{Path} refers to a directory.
-\item[sys\_enomem] Insufficient kernel memory.
-\item[sys\_erofs] \var{Path} is on a read-only filesystem. 
-\end{description}
-
-\SeeAlso
-\seef{Link}, \seef{SymLink}, \seem{Unlink}{2} 
-\end{function}
-For an example, see \seef{Link}.
-
-\begin{function}{Utime}
-\Declaration
-Function Utime (path : pathstr; utim : utimbuf) : Boolean;
-\Description
-\var{Utime} sets the access and modification times of a file.
-the \var{utimbuf} record contains 2 fields, \var{actime}, and \var{modtime},
-both of type Longint. They should be filled with an epoch-like time,
-specifying, respectively, the last access time, and the last modification
-time. 
-For some filesystem (most notably, FAT), these times are the same. 
-
-\Errors
-Errors are returned in \var{LinuxError}.
-\begin{description}
-\item[sys\_eaccess] One of the directories in \var{Path} has no
-search (=execute) permission.
-\item[sys\_enoent] A directory entry in \var{Path} does
-not exist or is a symbolic link pointing to a non-existent directory.
-\end{description}
-Other errors may occur, but aren't documented.
-
-\SeeAlso
-\seef{GetEpochTime}, \seef{Chown}, \seef{Access}, \seem{utime}(2)
-\end{function}
-
-\FPCexample{ex25}
-
-\begin{function}{WaitPid}
-\Declaration
-Function WaitPid (Pid : longint; Status : pointer; Options : Longint) : Longint;
-\Description
- \var{WaitPid} waits for a child process with process ID \var{Pid} to exit. The
-value of \var{Pid} can be one of the following:
-\begin{description}
-\item[Pid < -1] Causes \var{WaitPid} to wait for  any  child  process  whose
-              process group ID equals the absolute value of \var{pid}.
-\item[Pid = -1] Causes \var{WaitPid} to wait for any child process.
-\item[Pid = 0] Causes \var{WaitPid} to wait for  any  child  process  whose
-              process  group  ID  equals the one of the calling
-              process.
-\item[Pid > 0] Causes \var{WaitPid} to wait for the child whose process  ID
-equals the value of \var{Pid}.
-\end{description}
-The \var{Options} parameter can be used to specify further how \var{WaitPid}
-behaves:
-\begin{description}
-\item [WNOHANG] Causes \var{Waitpid} to return immediately if no child  has
-exited.
-\item [WUNTRACED] Causes \var{WaitPid} to return also for children which are
-stopped, but whose status has not yet been reported.
-\item[\_\_WCLONE] Causes \var{WaitPid} also to wait for threads created by
-the \seef{Clone} call.
-\end{description} 
-Upon return, it returns the exit status of the process, or -1 in case of
-failure. 
-
-\Errors
-Errors are returned in LinuxError.
-\SeeAlso
-\seef{Fork}, \seep{Execve}, \seem{waitpid}{2}
-\end{function}
-
-For an example, see \seef{Fork}.
-
-\begin{procedure}{WritePort}
-\Declaration
-Procedure WritePort (Port : Longint; Value : Byte);
-Procedure WritePort (Port : Longint; Value : Word);
-Procedure WritePort (Port : Longint; Value : Longint);
-\Description
-\var{WritePort} writes \var{Value} -- 1 byte, Word or longint -- 
-to port \var{Port}.
-
-Note: You need permission to write to a port. This permission can be set with root
-permission with the \var{IOperm} call.
-\Errors
-In case of an error (not enough permissions to write to this port), runtime 216 
-({\em Access Violation}) will occur.
-\SeeAlso
-\seef{IOperm}, \seep{WritePortB}, \seep{WritePortL}, \seep{WritePortW},
-\seep{ReadPortB}, \seep{ReadPortL}, \seep{ReadPortW}
-\end{procedure}
-
-
-\begin{procedure}{WritePortB}
-\Declaration
-Procedure WritePortB (Port : Longint; Value : Byte);
-Procedure WritePortB (Port : Longint; Var Buf; Count: longint);
-\Description
-The first form of \var{WritePortB} writes 1 byte to port \var{Port}.
-The second form writes \var{Count} bytes from \var{Buf} to port \var{Port}.
-
-Note: You need permission to write to a port. This permission can be set with root
-permission with the \var{IOperm} call.
-\Errors
-In case of an error (not enough permissions to write to this port), runtime 216 
-({\em Access Violation}) will occur.
-\SeeAlso
-\seef{IOperm}, \seep{WritePort}, \seep{WritePortL}, \seep{WritePortW},
-\seep{ReadPortB}, \seep{ReadPortL}, \seep{ReadPortW}
-\end{procedure}
-
-
-\begin{procedure}{WritePortL}
-\Declaration
-Procedure WritePortL (Port : Longint; Value : Longint);
-Procedure WritePortL (Port : Longint; Var Buf; Count: longint);
-\Description
-The first form of \var{WritePortB} writes 1 byte to port \var{Port}.
-The second form writes \var{Count} bytes from \var{Buf} to port \var{Port}.
-
-Note: You need permission to write to a port. This permission can be set with root
-permission with the \var{IOperm} call.
-\Errors
-In case of an error (not enough permissions to write to this port), runtime 216 
-({\em Access Violation}) will occur.
-\SeeAlso
-\seef{IOperm}, \seep{WritePort}, \seep{WritePortB}, \seep{WritePortW},
-\seep{ReadPortB}, \seep{ReadPortL}, \seep{ReadPortW}
-\end{procedure}
-
-
-\begin{procedure}{WritePortW}
-\Declaration
-Procedure WritePortW (Port : Longint; Var Buf; Count: longint);
-Procedure WritePortW (Port : Longint; Value : Word);
-\Description
-The first form of \var{WritePortB} writes 1 byte to port \var{Port}.
-The second form writes \var{Count} bytes from \var{Buf} to port \var{Port}.
-
-Note: You need permission to write to a port. This permission can be set with root
-permission with the \var{IOperm} call.
-\Errors
-In case of an error (not enough permissions to write to this port), runtime 216 
-({\em Access Violation}) will occur.
-\SeeAlso
-\seef{IOperm}, \seep{WritePort}, \seep{WritePortL}, \seep{WritePortB},
-\seep{ReadPortB}, \seep{ReadPortL}, \seep{ReadPortW}
-\end{procedure}
-

docs/math.tex

@@ -1,1006 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 2000 by Florian Klaempfl
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA.
-%
-\chapter{The MATH unit}
-\FPCexampledir{mathex}
-
-This chapter describes the \file{math} unit. The \var{math} unit
-was initially written by Florian Kl\"ampfl. It provides mathematical
-functions which aren't covered by the system unit.
-
-This chapter starts out with a definition of all types and constants
-that are defined, after which an overview is presented of the available 
-functions, grouped by category, and the last part contains a 
-complete explanation of each function.
-
-The following things must be taken into account when using this unit:
-\begin{enumerate}
-\item This unit is compiled in Object Pascal mode so all
-\var{integers} are 32 bit.
-\item Some overloaded functions exist for data arrays of integers and
-floats. When using the address operator (\var{@}) to pass an array of 
-data to such a function, make sure the address is typecasted to the 
-right type, or turn on the 'typed address operator' feature. failing to
-do so, will cause the compiler not be able to decide which function you 
-want to call.
-\end{enumerate}
-
-\section{Constants and types}
-
-The following types are defined in the \file{math} unit:
-\begin{verbatim}
-Type
-  Float = Extended;
-  PFloat = ^FLoat
-\end{verbatim}
-All calculations are done with the Float type. This allows to
-recompile the unit with a different float type to obtain a
-desired precision. The pointer type is used in functions that accept
-an array of values of arbitrary length.
-\begin{verbatim}
-Type
-   TPaymentTime = (PTEndOfPeriod,PTStartOfPeriod);
-\end{verbatim}
-\var{TPaymentTime} is used in the financial calculations.
-\begin{verbatim}
-Type
-   EInvalidArgument = Class(EMathError);
-\end{verbatim}
-The \var{EInvalidArgument} exception is used to report invalid arguments.
-
-\section{Function list by category}
-What follows is a listing of the available functions, grouped by category.
-For each function there is a reference to the page where you can find the
-function.
-\subsection{Min/max determination}
-Functions to determine the minimum or maximum of numbers:
-\begin{funclist}
-\funcref{max}{Maximum of 2 values}
-\funcref{maxIntValue}{Maximum of an array of integer values}
-\funcref{maxvalue}{Maximum of an array of values}
-\funcref{min}{Minimum of 2 values}
-\funcref{minIntValue}{Minimum of an array of integer values}
-\funcref{minvalue}{Minimum of an array of values}
-\end{funclist}
-\subsection{Angle conversion}
-\begin{funclist}
-\funcref{cycletorad}{convert cycles to radians}
-\funcref{degtograd}{convert degrees to grads}
-\funcref{degtorad}{convert degrees to radians}
-\funcref{gradtodeg}{convert grads to degrees}
-\funcref{gradtorad}{convert grads to radians}
-\funcref{radtocycle}{convert radians to cycles}
-\funcref{radtodeg}{convert radians to degrees}
-\funcref{radtograd}{convert radians to grads}
-\end{funclist}
-\subsection{Trigoniometric functions}
-\begin{funclist}
-\funcref{arccos}{calculate reverse cosine}
-\funcref{arcsin}{calculate reverse sine}
-\funcref{arctan2}{calculate reverse tangent}
-\funcref{cotan}{calculate cotangent}
-\procref{sincos}{calculate sine and cosine}
-\funcref{tan}{calculate tangent}
-\end{funclist}
-\subsection{Hyperbolic functions}
-\begin{funclist}
-\funcref{arcosh}{caculate reverse hyperbolic cosine}
-\funcref{arsinh}{caculate reverse hyperbolic sine}
-\funcref{artanh}{caculate reverse hyperbolic tangent}
-\funcref{cosh}{calculate hyperbolic cosine}
-\funcref{sinh}{calculate hyperbolic sine}
-\funcref{tanh}{calculate hyperbolic tangent}
-\end{funclist}
-\subsection{Exponential and logarithmic functions}
-\begin{funclist}
-\funcref{intpower}{Raise float to integer power}
-\funcref{ldexp}{Calculate $2^p x$}
-\funcref{lnxp1}{calculate \var{log(x+1)}}
-\funcref{log10}{calculate 10-base log}
-\funcref{log2}{calculate 2-base log}
-\funcref{logn}{calculate N-base log}
-\funcref{power}{raise float to arbitrary power}
-\end{funclist}
-\subsection{Number converting}
-\begin{funclist}
-\funcref{ceil}{Round to infinity}
-\funcref{floor}{Round to minus infinity}
-\procref{frexp}{Return mantissa and exponent}
-\end{funclist}
-\subsection{Statistical functions}
-\begin{funclist}
-\funcref{mean}{Mean of values}
-\procref{meanandstddev}{Mean and standard deviation of values}
-\procref{momentskewkurtosis}{Moments, skew and kurtosis}
-\funcref{popnstddev}{Population standarddeviation }
-\funcref{popnvariance}{Population variance}
-\funcref{randg}{Gaussian distributed randum value}
-\funcref{stddev}{Standard deviation}
-\funcref{sum}{Sum of values}
-\funcref{sumofsquares}{Sum of squared values}
-\procref{sumsandsquares}{Sum of values and squared values}
-\funcref{totalvariance}{Total variance of values}
-\funcref{variance}{variance of values}
-\end{funclist}
-\subsection{Geometrical functions}
-\begin{funclist}
-\funcref{hypot}{Hypotenuse of triangle}
-\funcref{norm}{Euclidian norm}
-\end{funclist}
-
-\section{Functions and Procedures}
-
-\begin{function}{arccos}
-\Declaration
-Function arccos(x : float) : float;
-\Description
-\var{Arccos} returns the inverse cosine of its argument \var{x}. The
-argument \var{x} should lie between -1 and 1 (borders included). 
-\Errors
-If the argument \var{x} is not in the allowed range, an
-\var{EInvalidArgument} exception is raised.
-\SeeAlso
-\seef{arcsin}, \seef{arcosh}, \seef{arsinh}, \seef{artanh}
-\end{function}
-
-\FPCexample{ex1}
-
-\begin{function}{arcosh}
-\Declaration
-Function arcosh(x : float) : float;
-Function arccosh(x : float) : float;
-\Description
-\var{Arcosh} returns the inverse hyperbolic cosine of its argument \var{x}. 
-The argument \var{x} should be larger than 1. 
-
-The \var{arccosh} variant of this function is supplied for \delphi 
-compatibility.
-\Errors
-If the argument \var{x} is not in the allowed range, an \var{EInvalidArgument}
-exception is raised.
-\SeeAlso
-\seef{cosh}, \seef{sinh}, \seef{arcsin}, \seef{arsinh}, \seef{artanh},
-\seef{tanh}
-\end{function}
-
-\FPCexample{ex3}
-
-\begin{function}{arcsin}
-\Declaration
-Function arcsin(x : float) : float;
-\Description
-\var{Arcsin} returns the inverse sine of its argument \var{x}. The
-argument \var{x} should lie between -1 and 1. 
-\Errors
-If the argument \var{x} is not in the allowed range, an \var{EInvalidArgument}
-exception is raised.
-\SeeAlso
-\seef{arccos}, \seef{arcosh}, \seef{arsinh}, \seef{artanh}
-\end{function}
-
-\FPCexample{ex2}
-
-
-\begin{function}{arctan2}
-\Declaration
-Function arctan2(x,y : float) : float;
-\Description
-\var{arctan2} calculates \var{arctan(y/x)}, and returns an angle in the
-correct quadrant. The returned angle will be in the range $-\pi$ to
-$\pi$ radians.
-The values of \var{x} and \var{y} must be between -2\^{}64 and 2\^{}64,
-moreover \var{x} should be different from zero.
-
-On Intel systems this function is implemented with the native intel
-\var{fpatan} instruction.
-\Errors
-If \var{x} is zero, an overflow error will occur.
-\SeeAlso
-\seef{arccos}, \seef{arcosh}, \seef{arsinh}, \seef{artanh}
-\end{function}
-
-\FPCexample{ex6}
-
-\begin{function}{arsinh}
-\Declaration
-Function arsinh(x : float) : float;
-Function arcsinh(x : float) : float;
-\Description
-\var{arsinh} returns the inverse hyperbolic sine of its argument \var{x}. 
-
-The \var{arscsinh} variant of this function is supplied for \delphi 
-compatibility.
-\Errors
-None.
-\SeeAlso
-\seef{arcosh}, \seef{arccos}, \seef{arcsin}, \seef{artanh}
-\end{function}
-
-\FPCexample{ex4}
-
-
-\begin{function}{artanh}
-\Declaration
-Function artanh(x : float) : float;
-Function arctanh(x : float) : float;
-\Description
-\var{artanh} returns the inverse hyperbolic tangent of its argument \var{x},
-where \var{x} should lie in the interval [-1,1], borders included.
-
-The \var{arctanh} variant of this function is supplied for \delphi compatibility.
-\Errors
-In case \var{x} is not in the interval [-1,1], an \var{EInvalidArgument}
-exception is raised.
-\SeeAlso
-\seef{arcosh}, \seef{arccos}, \seef{arcsin}, \seef{artanh}
-\Errors
-\SeeAlso
-\end{function}
-
-\FPCexample{ex5}
-
-
-\begin{function}{ceil}
-\Declaration
-Function ceil(x : float) : longint;
-\Description
-\var{Ceil} returns the lowest integer number greater than or equal to \var{x}.
-The absolute value of \var{x} should be less than \var{maxint}.
-\Errors
-If the asolute value of \var{x} is larger than maxint, an overflow error will
-occur.
-\SeeAlso
-\seef{floor}
-\end{function}
-
-\FPCexample{ex7}
-
-\begin{function}{cosh}
-\Declaration
-Function cosh(x : float) : float;
-\Description
-\var{Cosh} returns the hyperbolic cosine of it's argument {x}.
-\Errors
-None.
-\SeeAlso
-\seef{arcosh}, \seef{sinh}, \seef{arsinh}
-\end{function}
-
-\FPCexample{ex8}
-
-
-\begin{function}{cotan}
-\Declaration
-Function cotan(x : float) : float;
-\Description
-\var{Cotan} returns the cotangent of it's argument \var{x}. \var{x} should
-be different from zero.
-\Errors
-If \var{x} is zero then a overflow error will occur.
-\SeeAlso
-\seef{tanh}
-\end{function}
-
-\FPCexample{ex9}
-
-
-\begin{function}{cycletorad}
-\Declaration
-Function cycletorad(cycle : float) : float;
-\Description
-\var{Cycletorad} transforms it's argument \var{cycle}
-(an angle expressed in cycles) to radians.
-(1 cycle is $2 \pi$ radians).
-\Errors
-None.
-\SeeAlso
-\seef{degtograd}, \seef{degtorad}, \seef{radtodeg},
-\seef{radtograd}, \seef{radtocycle}
-\end{function}
-
-\FPCexample{ex10}
-
-
-\begin{function}{degtograd}
-\Declaration
-Function degtograd(deg : float) : float;
-\Description
-\var{Degtograd} transforms it's argument \var{deg} (an angle in degrees)
-to grads.
-
-(90 degrees is 100 grad.)
-\Errors
-None.
-\SeeAlso
-\seef{cycletorad}, \seef{degtorad}, \seef{radtodeg},
-\seef{radtograd}, \seef{radtocycle}
-\end{function}
-
-\FPCexample{ex11}
-
-
-\begin{function}{degtorad}
-\Declaration
-Function degtorad(deg : float) : float;
-\Description
-\var{Degtorad} converts it's argument \var{deg} (an angle in degrees) to
-radians.
-
-(pi radians is 180 degrees)
-\Errors
-None.
-\SeeAlso
-\seef{cycletorad}, \seef{degtograd}, \seef{radtodeg},
-\seef{radtograd}, \seef{radtocycle}
-\end{function}
-
-\FPCexample{ex12}
-
-
-\begin{function}{floor}
-\Declaration
-Function floor(x : float) : longint;
-\Description
-\var{Floor} returns the largest integer smaller than or equal to \var{x}.
-The absolute value of \var{x} should be less than \var{maxint}.
-\Errors
-If \var{x} is larger than \var{maxint}, an overflow will occur.
-\SeeAlso
-\seef{ceil}
-\end{function}
-
-\FPCexample{ex13}
-
-
-\begin{procedure}{frexp}
-\Declaration
-Procedure frexp(x : float;var mantissa : float; var exponent : integer);
-\Description
-\var{Frexp} returns the mantissa and exponent of it's argument
-\var{x} in \var{mantissa} and \var{exponent}.
-\Errors
-None
-\SeeAlso
-\end{procedure}
-
-\FPCexample{ex14}
-
-
-\begin{function}{gradtodeg}
-\Declaration
-Function gradtodeg(grad : float) : float;
-\Description
-\var{Gradtodeg} converts its argument \var{grad} (an angle in grads)
-to degrees.
-
-(100 grad is 90 degrees)
-\Errors
-None.
-\SeeAlso
-\seef{cycletorad}, \seef{degtograd}, \seef{radtodeg},
-\seef{radtograd}, \seef{radtocycle}, \seef{gradtorad}
-\end{function}
-
-\FPCexample{ex15}
-
-
-\begin{function}{gradtorad}
-\Declaration
-Function gradtorad(grad : float) : float;
-\Description
-\var{Gradtorad} converts its argument \var{grad} (an angle in grads)
-to radians.
-
-(200 grad is pi degrees).
-\Errors
-None.
-\SeeAlso
-\seef{cycletorad}, \seef{degtograd}, \seef{radtodeg},
-\seef{radtograd}, \seef{radtocycle}, \seef{gradtodeg}
-\end{function}
-
-\FPCexample{ex16}
-
-
-\begin{function}{hypot}
-\Declaration
-Function hypot(x,y : float) : float;
-\Description
-\var{Hypot} returns the hypotenuse of the triangle where the sides
-adjacent to the square angle have lengths \var{x} and \var{y}.
-
-The function uses Pythagoras' rule for this.
-\Errors
-None.
-\SeeAlso
-\end{function}
-
-\FPCexample{ex17}
-
-
-\begin{function}{intpower}
-\Declaration
-Function intpower(base : float;exponent : longint) : float;
-\Description
-\var{Intpower} returns \var{base} to the power \var{exponent},
-where exponent is an integer value.
-\Errors
-If \var{base} is zero and the exponent is negative, then an
-overflow error will occur.
-\SeeAlso
-\seef{power}
-\end{function}
-
-\FPCexample{ex18}
-
-
-\begin{function}{ldexp}
-\Declaration
-Function ldexp(x : float;p : longint) : float;
-\Description
-\var{Ldexp} returns $2^p x$.
-\Errors
-None.
-\SeeAlso
-\seef{lnxp1}, \seef{log10},\seef{log2},\seef{logn}
-\end{function}
-
-\FPCexample{ex19}
-
-
-\begin{function}{lnxp1}
-\Declaration
-Function lnxp1(x : float) : float;
-\Description
-\var{Lnxp1} returns the natural logarithm of \var{1+X}. The result
-is more precise for small values of \var{x}. \var{x} should be larger
-than -1.
-\Errors
-If $x\leq -1$ then an \var{EInvalidArgument} exception will be raised.
-\SeeAlso
-\seef{ldexp}, \seef{log10},\seef{log2},\seef{logn}
-\end{function}
-
-\FPCexample{ex20}
-
-\begin{function}{log10}
-\Declaration
-Function log10(x : float) : float;
-\Description
-\var{Log10} returns the 10-base logarithm of \var{X}.
-\Errors
-If \var{x} is less than or equal to 0 an 'invalid fpu operation' error
-will occur.
-\SeeAlso
-\seef{ldexp}, \seef{lnxp1},\seef{log2},\seef{logn}
-\end{function}
-
-\FPCexample{ex21}
-
-
-\begin{function}{log2}
-\Declaration
-Function log2(x : float) : float;
-\Description
-\var{Log2} returns the 2-base logarithm of \var{X}.
-\Errors
-If \var{x} is less than or equal to 0 an 'invalid fpu operation' error
-will occur.
-\SeeAlso
-\seef{ldexp}, \seef{lnxp1},\seef{log10},\seef{logn}
-\end{function}
-
-\FPCexample{ex22}
-
-
-\begin{function}{logn}
-\Declaration
-Function logn(n,x : float) : float;
-\Description
-\var{Logn} returns the n-base logarithm of \var{X}.
-\Errors
-If \var{x} is less than or equal to 0 an 'invalid fpu operation' error
-will occur.
-\SeeAlso
-\seef{ldexp}, \seef{lnxp1},\seef{log10},\seef{log2}
-\end{function}
-
-\FPCexample{ex23}
-
-\begin{function}{max}
-\Declaration
-Function max(Int1,Int2:Cardinal):Cardinal;
-Function max(Int1,Int2:Integer):Integer;
-\Description
-\var{Max} returns the maximum of \var{Int1} and \var{Int2}.
-\Errors
-None.
-\SeeAlso
-\seef{min}, \seef{maxIntValue}, \seef{maxvalue}
-\end{function}
-
-\FPCexample{ex24}
-
-\begin{function}{maxIntValue}
-\Declaration
-function MaxIntValue(const Data: array of Integer): Integer;
-\Description
-\var{MaxIntValue} returns the largest integer out of the \var{Data}
-array.
-
-This function is provided for \delphi compatibility, use the \seef{maxvalue}
-function instead.
-\Errors
-None.
-\SeeAlso
-\seef{maxvalue}, \seef{minvalue}, \seef{minIntValue}
-\end{function}
-
-\FPCexample{ex25}
-
-
-\begin{function}{maxvalue}
-\Declaration
-Function maxvalue(const data : array of float) : float;
-Function maxvalue(const data : array of Integer) : Integer;
-Function maxvalue(const data : PFloat; Const N : Integer) : float;
-Function maxvalue(const data : PInteger; Const N : Integer) : Integer;
-\Description
-\var{Maxvalue} returns the largest value in the \var{data} 
-array with integer or float values. The return value has 
-the same type as the elements of the array.
-
-The third and fourth forms accept a pointer to an array of \var{N} 
-integer or float values.
-\Errors
-None.
-\SeeAlso
-\seef{maxIntValue}, \seef{minvalue}, \seef{minIntValue}
-\end{function}
-
-\FPCexample{ex26}
-
-\begin{function}{mean}
-\Declaration
-Function mean(const data : array of float) : float;
-Function mean(const data : PFloat; Const N : longint) : float;
-\Description
-\var{Mean} returns the average value of \var{data}.
-
-The second form accepts a pointer to an array of \var{N} values.
-\Errors
-None.
-\SeeAlso
-\seep{meanandstddev}, \seep{momentskewkurtosis}, \seef{sum}
-\end{function}
-
-\FPCexample{ex27}
-
-\begin{procedure}{meanandstddev}
-\Declaration
-Procedure meanandstddev(const data : array of float; 
-                        var mean,stddev : float);
-procedure meanandstddev(const data : PFloat;
-  Const N : Longint;var mean,stddev : float);
-\Description
-\var{meanandstddev} calculates the mean and standard deviation of \var{data}
-and returns the result in \var{mean} and \var{stddev}, respectively.
-Stddev is zero if there is only one value.
-
-The second form accepts a pointer to an array of \var{N} values.
-\Errors
-None.
-\SeeAlso
-\seef{mean},\seef{sum}, \seef{sumofsquares}, \seep{momentskewkurtosis}
-\end{procedure}
-
-\FPCexample{ex28}
-
-
-\begin{function}{min}
-\Declaration
-Function min(Int1,Int2:Cardinal):Cardinal;
-Function min(Int1,Int2:Integer):Integer;
-\Description
-\var{min} returns the smallest value of \var{Int1} and \var{Int2};
-\Errors
-None.
-\SeeAlso
-\seef{max}
-\end{function}
-
-\FPCexample{ex29}
-
-\begin{function}{minIntValue}
-\Declaration
-Function minIntValue(const Data: array of Integer): Integer;
-\Description
-\var{MinIntvalue} returns the smallest value in the \var{Data} array.
-
-This function is provided for \delphi compatibility, use \var{minvalue}
-instead.
-\Errors
-None
-\SeeAlso
-\seef{minvalue}, \seef{maxIntValue}, \seef{maxvalue}
-\end{function}
-
-\FPCexample{ex30}
-
-
-\begin{function}{minvalue}
-\Declaration
-Function minvalue(const data : array of float) : float;
-Function minvalue(const data : array of Integer) : Integer;
-Function minvalue(const data : PFloat; Const N : Integer) : float;
-Function minvalue(const data : PInteger; Const N : Integer) : Integer;
-\Description
-\var{Minvalue} returns the smallest value in the \var{data} 
-array with integer or float values. The return value has 
-the same type as the elements of the array.
-
-The third and fourth forms accept a pointer to an array of \var{N} 
-integer or float values.
-\Errors
-None.
-\SeeAlso
-\seef{maxIntValue}, \seef{maxvalue}, \seef{minIntValue}
-\end{function}
-
-\FPCexample{ex31}
-
-
-\begin{procedure}{momentskewkurtosis}
-\Declaration
-procedure momentskewkurtosis(const data : array of float;
-  var m1,m2,m3,m4,skew,kurtosis : float);
-procedure momentskewkurtosis(const data : PFloat; Const N : Integer;
-  var m1,m2,m3,m4,skew,kurtosis : float);
-\Description
-\var{momentskewkurtosis} calculates the 4 first moments of the distribution
-of valuesin \var{data} and returns them in \var{m1},\var{m2},\var{m3} and
-\var{m4}, as well as the \var{skew} and \var{kurtosis}.
-\Errors
-None.
-\SeeAlso
-\seef{mean}, \seep{meanandstddev}
-\end{procedure}
-
-\FPCexample{ex32}
-
-\begin{function}{norm}
-\Declaration
-Function norm(const data : array of float) : float;
-Function norm(const data : PFloat; Const N : Integer) : float;
-\Description
-\var{Norm} calculates the Euclidian norm of the array of data.
-This equals \var{sqrt(sumofsquares(data))}.
-
-The second form accepts a pointer to an array of \var{N} values.
-\Errors
-None.
-\SeeAlso
-\seef{sumofsquares}
-\end{function}
-
-\FPCexample{ex33}
-
-
-\begin{function}{popnstddev}
-\Declaration
-Function popnstddev(const data : array of float) : float;
-Function popnstddev(const data : PFloat; Const N : Integer) : float;
-\Description
-\var{Popnstddev} returns the square root of the population variance of
-the values in the  \var{Data} array. It returns zero if there is only one value.
-
-The second form of this function accepts a pointer to an array of \var{N}
-values.
-\Errors
-None.
-\SeeAlso
-\seef{popnvariance}, \seef{mean}, \seep{meanandstddev}, \seef{stddev},
-\seep{momentskewkurtosis}
-\end{function}
-
-\FPCexample{ex35}
-
-
-\begin{function}{popnvariance}
-\Declaration
-Function popnvariance(const data : array of float) : float;
-Function popnvariance(const data : PFloat; Const N : Integer) : float;
-\Description
-\var{Popnvariance} returns the square root of the population variance of
-the values in the  \var{Data} array. It returns zero if there is only one value.
-
-The second form of this function accepts a pointer to an array of \var{N}
-values.
-\Errors
-None.
-\SeeAlso
-\seef{popnstddev}, \seef{mean}, \seep{meanandstddev}, \seef{stddev},
-\seep{momentskewkurtosis}
-\end{function}
-
-\FPCexample{ex36}
-
-
-\begin{function}{power}
-\Declaration
-Function power(base,exponent : float) : float;
-\Description
-\var{power} raises \var{base} to the power \var{power}. This is equivalent
-to \var{exp(power*ln(base))}. Therefore \var{base} should be non-negative.
-\Errors
-None.
-\SeeAlso
-\seef{intpower}
-\end{function}
-
-\FPCexample{ex34}
-
-
-\begin{function}{radtocycle}
-\Declaration
-Function radtocycle(rad : float) : float;
-\Description
-\var{Radtocycle} converts its argument \var{rad} (an angle expressed in
-radians) to an angle in cycles.
-
-(1 cycle equals 2 pi radians)
-\Errors
-None.
-\SeeAlso
-\seef{degtograd}, \seef{degtorad}, \seef{radtodeg},
-\seef{radtograd}, \seef{cycletorad}
-\end{function}
-
-\FPCexample{ex37}
-
-
-\begin{function}{radtodeg}
-\Declaration
-Function radtodeg(rad : float) : float;
-\Description
-\var{Radtodeg} converts its argument \var{rad} (an angle expressed in
-radians) to an angle in degrees.
-
-(180 degrees equals pi radians)
-\Errors
-None.
-\SeeAlso
-\seef{degtograd}, \seef{degtorad}, \seef{radtocycle},
-\seef{radtograd}, \seef{cycletorad}
-\end{function}
-
-\FPCexample{ex38}
-
-
-\begin{function}{radtograd}
-\Declaration
-Function radtograd(rad : float) : float;
-\Description
-\var{Radtodeg} converts its argument \var{rad} (an angle expressed in
-radians) to an angle in grads.
-
-(200 grads equals pi radians)
-\Errors
-None.
-\SeeAlso
-\seef{degtograd}, \seef{degtorad}, \seef{radtocycle},
-\seef{radtodeg}, \seef{cycletorad}
-\end{function}
-
-\FPCexample{ex39}
-
-
-\begin{function}{randg}
-\Declaration
-Function randg(mean,stddev : float) : float;
-\Description
-\var{randg} returns a random number which - when produced in large
-quantities - has a Gaussian distribution with mean \var{mean} and 
-standarddeviation \var{stddev}. 
-\Errors
-None.
-\SeeAlso
-\seef{mean}, \seef{stddev}, \seep{meanandstddev}
-\end{function}
-
-\FPCexample{ex40}
-
-
-\begin{procedure}{sincos}
-\Declaration
-Procedure sincos(theta : float;var sinus,cosinus : float);
-\Description
-\var{Sincos} calculates the sine and cosine of the angle \var{theta},
-and returns the result in \var{sinus} and \var{cosinus}.
-
-On Intel hardware, This calculation will be faster than making 2 calls
-to clculatet he sine and cosine separately.
-\Errors
-None.
-\SeeAlso
-\seef{arcsin}, \seef{arccos}.
-\end{procedure}
-
-\FPCexample{ex41}
-
-
-\begin{function}{sinh}
-\Declaration
-Function sinh(x : float) : float;
-\Description
-\var{Sinh} returns the hyperbolic sine of its argument \var{x}.
-\Errors
-\SeeAlso
-\seef{cosh}, \seef{arsinh}, \seef{tanh}, \seef{artanh}
-\end{function}
-
-\FPCexample{ex42}
-
-
-\begin{function}{stddev}
-\Declaration
-Function stddev(const data : array of float) : float;
-Function stddev(const data : PFloat; Const N : Integer) : float;
-\Description
-\var{Stddev} returns the standard deviation of the values in \var{Data}.
-It returns zero if there is only one value.
-
-The second form of the function accepts a pointer to an array of \var{N}
-values.
-\Errors
-None.
-\SeeAlso
-\seef{mean}, \seep{meanandstddev}, \seef{variance}, \seef{totalvariance}
-\end{function}
-
-\FPCexample{ex43}
-
-
-\begin{function}{sum}
-\Declaration
-Function sum(const data : array of float) : float;
-Function sum(const data : PFloat; Const N : Integer) : float;
-\Description
-\var{Sum} returns the sum of the values in the \var{data} array.
-
-The second form of the function accepts a pointer to an array of \var{N}
-values.
-\Errors
-None.
-\SeeAlso
-\seef{sumofsquares}, \seep{sumsandsquares}, \seef{totalvariance}
-, \seef{variance}
-\end{function}
-
-\FPCexample{ex44}
-
-
-\begin{function}{sumofsquares}
-\Declaration
-Function sumofsquares(const data : array of float) : float;
-Function sumofsquares(const data : PFloat; Const N : Integer) : float;
-\Description
-\var{Sumofsquares} returns the sum of the squares of the values in the \var{data} 
-array.
-
-The second form of the function accepts a pointer to an array of \var{N}
-values.
-\Errors
-None.
-\SeeAlso
-\seef{sum}, \seep{sumsandsquares}, \seef{totalvariance}
-, \seef{variance}
-\end{function}
-
-\FPCexample{ex45}
-
-
-\begin{procedure}{sumsandsquares}
-\Declaration
-Procedure sumsandsquares(const data : array of float;
-  var sum,sumofsquares : float);
-Procedure sumsandsquares(const data : PFloat; Const N : Integer;
-  var sum,sumofsquares : float);
-\Description
-\var{sumsandsquares} calculates the sum of the values and the sum of 
-the squares of the values in the \var{data} array and returns the
-results in \var{sum} and \var{sumofsquares}.
-
-The second form of the function accepts a pointer to an array of \var{N}
-values.
-\Errors
-None.
-\SeeAlso
-\seef{sum}, \seef{sumofsquares}, \seef{totalvariance}
-, \seef{variance}
-\end{procedure}
-
-\FPCexample{ex46}
-
-
-\begin{function}{tan}
-\Declaration
-Function tan(x : float) : float;
-\Description
-\var{Tan} returns the tangent of \var{x}.
-\Errors
-If \var{x} (normalized) is pi/2 or 3pi/2 then an overflow will occur.
-\SeeAlso
-\seef{tanh}, \seef{arcsin}, \seep{sincos}, \seef{arccos}
-\end{function}
-
-\FPCexample{ex47}
-
-
-\begin{function}{tanh}
-\Declaration
-Function tanh(x : float) : float;
-\Description
-\var{Tanh} returns the hyperbolic tangent of \var{x}.
-\Errors
-None.
-\SeeAlso
-\seef{arcsin}, \seep{sincos}, \seef{arccos}
-\end{function}
-
-\FPCexample{ex48}
-
-
-\begin{function}{totalvariance}
-\Declaration
-Function totalvariance(const data : array of float) : float;
-Function totalvariance(const data : PFloat; Const N : Integer) : float;
-\Description
-\var{TotalVariance} returns the total variance of the values in the 
-\var{data} array. It returns zero if there is only one value.
-
-The second form of the function accepts a pointer to an array of \var{N}
-values.
-\Errors
-None.
-\SeeAlso
-\seef{variance}, \seef{stddev}, \seef{mean}
-\end{function}
-
-\FPCexample{ex49}
-
-
-\begin{function}{variance}
-\Declaration
-Function variance(const data : array of float) : float;
-Function variance(const data : PFloat; Const N : Integer) : float;
-\Description
-\var{Variance} returns the variance of the values in the 
-\var{data} array. It returns zero if there is only one value.
-
-The second form of the function accepts a pointer to an array of \var{N}
-values.
-\Errors
-None.
-\SeeAlso
-\seef{totalvariance}, \seef{stddev}, \seef{mean}
-\end{function}
-
-\FPCexample{ex50}

docs/mmx.tex

@@ -1,96 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1997, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA. 
-%
-\chapter{The MMX unit}
-This chapter describes the \file{MMX} unit. This unit allows you to use the
-\var{MMX} capabilities of the \fpc compiler. It was written by Florian
-Kl\"ampfl for the \var{I386} processor. It should work on all platforms that
-use the Intel processor.
-\section{Variables, Types and constants}
-The following types are defined in the \var{MMX} unit:
-\begin{verbatim}
-tmmxshortint = array[0..7] of shortint;
-tmmxbyte = array[0..7] of byte;
-tmmxword = array[0..3] of word;
-tmmxinteger = array[0..3] of integer;
-tmmxfixed = array[0..3] of fixed16;
-tmmxlongint = array[0..1] of longint;
-tmmxcardinal = array[0..1] of cardinal;
-{ for the AMD 3D }
-tmmxsingle = array[0..1] of single;
-\end{verbatim}
-And the following pointers to the above types:
-\begin{verbatim}
-pmmxshortint = ^tmmxshortint;
-pmmxbyte = ^tmmxbyte;
-pmmxword = ^tmmxword;
-pmmxinteger = ^tmmxinteger;
-pmmxfixed = ^tmmxfixed;
-pmmxlongint = ^tmmxlongint;
-pmmxcardinal = ^tmmxcardinal;
-{ for the AMD 3D }
-pmmxsingle = ^tmmxsingle;
-\end{verbatim}
-The following initialized constants allow you to determine if the computer
-has \var{MMX} extensions. They are set correctly in the unit's
-initialization code.
-\begin{verbatim}
-is_mmx_cpu : boolean = false;
-is_amd_3d_cpu : boolean = false;
-\end{verbatim}
-\section{Functions and Procedures}
-\begin{procedure}{Emms}
-\Declaration
-Procedure Emms ;
-
-\Description
-\var{Emms} sets all floating point registers to empty. This procedure must
-be called after you have used any \var{MMX} instructions, if you want to use
-floating point arithmetic. If you just want to move floating point data
-around, it isn't necessary to call this function, the compiler doesn't use
-the FPU registers when moving data. Only when doing calculations, you should
-use this function.
-
-\Errors
-None.
-\SeeAlso
- \progref 
-\end{procedure}
-\begin{FPCList}
-\item[Example:]
-\begin{verbatim}
-Program MMXDemo;
-uses mmx;
-var
-   d1 : double;
-   a : array[0..10000] of double;
-   i : longint;
-begin
-   d1:=1.0;
-{$mmx+}
-   { floating point data is used, but we do _no_ arithmetic }
-   for i:=0 to 10000 do
-     a[i]:=d2;  { this is done with 64 bit moves }
-{$mmx-}
-   emms;   { clear fpu }
-   { now we can do floating point arithmetic again }
-end. 
-\end{verbatim}
-\end{FPCList}

docs/mouse.tex

@@ -1,353 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1997, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA.
-%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% The Mouse unit
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\chapter{The MOUSE unit}
-\FPCexampledir{mouseex}
-The \var{Mouse} unit implements a platform independent mouse handling 
-interface. It is implemented identically on all platforms supported by 
-\fpc{} and can be enhanced with custom drivers, should this be needed.
-It is intended to be used only in text-based screens, for instance in 
-conjunction with the keyboard and video unit. No support for graphical
-screens is implemented, and there are (currently) no plans to implement
-this.
-
-\section{Constants, Types and Variables}
-\subsection{Constants}	
-The following constants can be used when mouse drivers need to report 
-errors:
-\begin{verbatim}
-const
-  { We have an errorcode base of 1030 }
-  errMouseBase                    = 1030;
-  errMouseInitError               = errMouseBase + 0;
-  errMouseNotImplemented          = errMouseBase + 1;
-\end{verbatim}
-The following constants describe which action a mouse event describes
-\begin{verbatim}
-const
-  MouseActionDown = $0001;  { Mouse down event }
-  MouseActionUp   = $0002;  { Mouse up event }
-  MouseActionMove = $0004;  { Mouse move event }
-\end{verbatim}
-The following constants describe the used buttons in a mouse event:
-\begin{verbatim}
-  MouseLeftButton   = $01;  { Left mouse button }
-  MouseRightButton  = $02;  { Right mouse button }
-  MouseMiddleButton = $04;  { Middle mouse button }
-\end{verbatim}
-The mouse unit has a mechanism to buffer mouse events. The following
-constant defines the size of the event buffer:
-\begin{verbatim}
-MouseEventBufSize = 16;
-\end{verbatim}
-\subsection{Types}
-The \var{TMouseEvent} is the central type of the mouse unit, it is used
-to describe the mouse events:
-\begin{verbatim}
-PMouseEvent=^TMouseEvent;
-TMouseEvent=packed record { 8 bytes }
-  buttons : word;
-  x,y     : word;
-  Action  : word;
-end;
-\end{verbatim}
-The \var{Buttons} field describes which buttons were down when the event
-occurred. The \var{x,y} fields describe where the event occurred on the
-screen. The \var{Action} describes what action was going on when the event
-occurred. The \var{Buttons} and \var{Action} field can be examined using the
-above constants.
-
-The following record is used to implement a mouse driver in the
-\seep{SetMouseDriver} function:
-\begin{verbatim}
-TMouseDriver = Record 
-  UseDefaultQueue : Boolean;
-  InitDriver : Procedure;
-  DoneDriver : Procedure;
-  DetectMouse : Function : Byte;
-  ShowMouse : Procedure;
-  HideMouse : Procedure;
-  GetMouseX : Function : Word;
-  GetMouseY : Function : Word;
-  GetMouseButtons : Function : Word;
-  SetMouseXY : procedure (x,y:word);
-  GetMouseEvent : procedure (var MouseEvent:TMouseEvent);
-  PollMouseEvent : function (var MouseEvent: TMouseEvent):boolean;
-  PutMouseEvent : procedure (Const MouseEvent:TMouseEvent); 
-end;
-\end{verbatim}
-Its fields will be explained in the section on writing a custom driver.
-
-\subsection{Variables}
-The following variables are used to keep the current position and state of
-the mouse.
-\begin{verbatim}
-MouseIntFlag : Byte;  { Mouse in int flag }
-MouseButtons : Byte;  { Mouse button state }
-MouseWhereX,
-MouseWhereY  : Word;  { Mouse position }
-\end{verbatim}
-
-\section{Functions and procedures}
-
-\begin{function}{DetectMouse}
-\Declaration
-Function DetectMouse:byte;
-\Description
-\var{DetectMouse} detects whether a mouse is attached to the system or not.
-If there is no mouse, then zero is returned. If a mouse is attached, then
-the number of mouse buttons is returned.
-
-This function should be called after the mouse driver was initialized.
-\Errors
-None.
-\SeeAlso
-\seep{InitMouse},\seep{DoneMouse},
-\end{function}
-
-\FPCexample{ex1}
-
-\begin{procedure}{DoneMouse}
-\Declaration
-Procedure DoneMouse;
-\Description
-\var{DoneMouse} De-initializes the mouse driver. It cleans up any memory
-allocated when the mouse was initialized, or removes possible mouse hooks
-from memory. The mouse functions will not work after \var{DoneMouse} was
-called. If \var{DoneMouse} is called a second time, it will exit at once.
-\var{InitMouse} should be called before \var{DoneMouse} can be called again.
-\Errors
-None.
-\SeeAlso
-\seef{DetectMouse}, \seep{InitMouse}
-\end{procedure}
-
-For an example, see most other mouse functions.
-
-\begin{function}{GetMouseButtons}
-\Declaration
-Function GetMouseButtons:word;
-\Description
-\var{GetMouseButtons} returns the current button state of the mouse, i.e.
-it returns a or-ed combination of the following constants:
-\begin{description}
-\item[MouseLeftButton] When the left mouse button is held down.
-\item[MouseRightButton] When the right mouse button is held down.
-\item[MouseMiddleButton] When the middle mouse button is held down.
-\end{description}
-\Errors
-None.
-\SeeAlso
-\seep{GetMouseEvent}, \seef{GetMouseX}, \seef{GetMouseY}
-\end{function}
-
-\FPCexample{ex2}
-
-\begin{procedure}{GetMouseDriver}
-\Declaration
-Procedure GetMouseDriver(Var Driver : TMouseDriver);
-\Description
-\var{GetMouseDriver} returns the currently set mouse driver. It can be used
-to retrieve the current mouse driver, and override certain callbacks.
-
-A more detailed explanation about getting and setting mouse drivers can be found in
-\sees{mousedrv}.
-
-\Errors
-None.
-\SeeAlso
-\seep{SetMouseDriver}
-\end{procedure}
-
-For an example, see the section on writing a custom mouse driver,
-\sees{mousedrv}
-
-\begin{procedure}{GetMouseEvent}
-\Declaration
-Procedure GetMouseEvent(var MouseEvent:TMouseEvent);
-\Description
-\var{GetMouseEvent} returns the next mouse event (a movement, button press or
-button release), and waits for one if none is available in the queue.
-
-Some mouse drivers can implement a mouse event queue which can hold multiple
-events till they are fetched.; Others don't, and in that case, a one-event
-queue is implemented for use with \seef{PollMouseEvent}.
-\Errors
-None.
-\SeeAlso
-\seef{GetMouseButtons}, \seef{GetMouseX}, \seef{GetMouseY}
-\end{procedure}
-
-\begin{function}{GetMouseX}
-\Declaration
-Function GetMouseX:word;
-\Description
-\var{GetMouseX} returns the current \var{X} position of the mouse. \var{X} is
-measured in characters, starting at 0 for the left side of the screen.
-\Errors
-None.
-\SeeAlso
-\seef{GetMouseButtons},\seep{GetMouseEvent}, \seef{GetMouseY}
-\end{function}
-
-\FPCexample{ex4}
-
-\begin{function}{GetMouseY}
-\Declaration
-Function GetMouseY:word; 
-\Description
-\var{GetMouseY} returns the current \var{Y} position of the mouse. \var{Y} is
-measured in characters, starting at 0 for the top of the screen.
-\Errors
-None.
-\SeeAlso
-\seef{GetMouseButtons},\seep{GetMouseEvent}, \seef{GetMouseX}
-\end{function}
-
-For an example, see \seef{GetMouseX}
-
-\begin{procedure}{HideMouse}
-\Declaration
-Procedure HideMouse;
-\Description
-\var{HideMouse} hides the mouse cursor. This may or may not be implemented
-on all systems, and depends on the driver.
-\Errors
-None.
-\SeeAlso
-\seep{ShowMouse}
-\end{procedure}
-
-\FPCexample{ex5}
-
-\begin{procedure}{InitMouse}
-\Declaration
-Procedure InitMouse;
-\Description
-\var{InitMouse} Initializes the mouse driver. This will allocate any data
-structures needed for the mouse to function. All mouse functions can be
-used after a call to \var{InitMouse}.
-
-A call to \var{InitMouse} must always be followed by a call to \seep{DoneMouse}
-at program exit. Failing to do so may leave the mouse in an unusable state,
-or may result in memory leaks.
-\Errors
-None.
-\SeeAlso
-\seep{DoneMouse}, \seef{DetectMouse}
-\end{procedure}
-
-For an example, see most other functions.
-
-\begin{function}{PollMouseEvent}
-\Declaration
-Function PollMouseEvent(var MouseEvent: TMouseEvent):boolean; 
-\Description
-\var{PollMouseEvent} checks whether a mouse event is available, and 
-returns it in \var{MouseEvent} if one is found. The function result is
-\var{True} in that case. If no mouse event is pending, the function result
-is \var{False}, and the contents of \var{MouseEvent} is undefined.
-
-Note that after a call to \var{PollMouseEvent}, the event should still 
-be removed from the mouse event queue with a call to \var{GetMouseEvent}.
-\Errors
-None.
-\SeeAlso
-\seep{GetMouseEvent}, \seep{PutMouseEvent}
-\end{function}
-
-\begin{procedure}{PutMouseEvent}
-\Declaration
-Procedure PutMouseEvent(const MouseEvent: TMouseEvent);
-\Description
-\var{PutMouseEvent} adds \var{MouseEvent} to the input queue. The next
-call to \seep{GetMouseEvent} or \var{PollMouseEvent} will then return
-\var{MouseEvent}. 
-
-Please note that depending on the implementation the mouse event queue
-can hold only one value.
-\Errors
-None.
-\SeeAlso
-\seep{GetMouseEvent}, \seef{PollMouseEvent}
-\end{procedure}
-
-\begin{procedure}{SetMouseDriver}
-\Declaration
-Procedure SetMouseDriver(Const Driver : TMouseDriver);
-\Description
-\var{SetMouseDriver} sets the mouse driver to \var{Driver}. This function
-should be called before \seep{InitMouse} is called, or after \var{DoneMouse}
-is called. If it is called after the mouse has been initialized, it does
-nothing.
-
-For more information on setting the mouse driver, \sees{mousedrv}.
-\Errors
-
-\SeeAlso
-\seep{InitMouse}, \seep{DoneMouse}, \seep{GetMouseDriver}
-\end{procedure}
-
-For an example, see \sees{mousedrv}
-
-\begin{procedure}{SetMouseXY}
-\Declaration
-Procedure SetMouseXY(x,y:word); 
-\Description
-\var{SetMouseXY} places the mouse cursor on \var{X,Y}. X and Y are zero
-based character coordinates: \var{0,0} is the top-left corner of the screen,
-and the position is in character cells (i.e. not in pixels).
-\Errors
-None.
-\SeeAlso
-\seef{GetMouseX}, \seef{GetMouseY}
-\end{procedure}
-
-\FPCexample{ex7}
-
-\begin{procedure}{ShowMouse}
-\Declaration
-Procedure ShowMouse; 
-\Description
-\var{ShowMouse} shows the mouse cursor if it was previously hidden. The
-capability to hide or show the mouse cursor depends on the driver.
-\Errors
-None.
-\SeeAlso
-\seep{HideMouse}
-\end{procedure}
-
-For an example, see \seep{HideMouse}
-
-\section{Writing a custom mouse driver}
-\label{se:mousedrv}
-The \file{mouse} has support for adding a custom mouse driver. This can be
-used to add support for mouses not supported by the standard \fpc{} driver,
-but also to enhance an existing driver for instance to log mouse events or
-to implement a record and playback function. 
-
-The following unit shows how a mouse driver can be enhanced by adding some
-logging capabilities to the driver.
-\FPCexample{logmouse}

docs/objects.tex

@@ -1,2530 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1998, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA. 
-%
-\chapter{The Objects unit.}
-\label{ch:objectsunit}
-
-\FPCexampledir{objectex}
-This chapter documents the \file{objects} unit. The unit was implemented by
-many people, and was mainly taken from the FreeVision sources. It has been 
-ported to all supported platforms.
-
-The methods and fields that are in a \var{Private} part of an object
-declaration have been left out of this documentation.
-
-\section{Constants}
-The following constants are error codes, returned by the various stream
-objects.
-
-\begin{verbatim}
-CONST
-   stOk         =  0; { No stream error }
-   stError      = -1; { Access error }
-   stInitError  = -2; { Initialize error }
-   stReadError  = -3; { Stream read error }
-   stWriteError = -4; { Stream write error }
-   stGetError   = -5; { Get object error }
-   stPutError   = -6; { Put object error }
-   stSeekError  = -7; { Seek error in stream }
-   stOpenError  = -8; { Error opening stream }
-\end{verbatim}
-These constants can be passed to constructors of file streams:
-\begin{verbatim}
-CONST
-   stCreate    = $3C00; { Create new file }
-   stOpenRead  = $3D00; { Read access only }
-   stOpenWrite = $3D01; { Write access only }
-   stOpen      = $3D02; { Read/write access }
-\end{verbatim}
-
-The following constants are error codes, returned by the collection list
-objects:
-\begin{verbatim}
-CONST
-   coIndexError = -1; { Index out of range }
-   coOverflow   = -2; { Overflow }
-\end{verbatim}
-
-Maximum data sizes (used in determining how many data can be used.
-
-\begin{verbatim}
-CONST
-   MaxBytes = 128*1024*1024;                          { Maximum data size }
-   MaxWords = MaxBytes DIV SizeOf(Word);              { Max word data size }
-   MaxPtrs = MaxBytes DIV SizeOf(Pointer);            { Max ptr data size }
-   MaxCollectionSize = MaxBytes DIV SizeOf(Pointer);  { Max collection size }
-\end{verbatim}
-
-\section{Types}
-The follwing auxiliary types are defined:
-\begin{verbatim}
-TYPE
-   { Character set }
-   TCharSet = SET Of Char;                            
-   PCharSet = ^TCharSet;
-
-   { Byte array }
-   TByteArray = ARRAY [0..MaxBytes-1] Of Byte;        
-   PByteArray = ^TByteArray;
-
-   { Word array }
-   TWordArray = ARRAY [0..MaxWords-1] Of Word;        
-   PWordArray = ^TWordArray;
-
-   { Pointer array }
-   TPointerArray = Array [0..MaxPtrs-1] Of Pointer;   
-   PPointerArray = ^TPointerArray; 
-
-   { String pointer }
-   PString = ^String;
-
-   { Filename array }
-   AsciiZ = Array [0..255] Of Char;
-
-   Sw_Word    = Cardinal;
-   Sw_Integer = LongInt;
-\end{verbatim}
-The following records are used internaly for easy type conversion:
-\begin{verbatim}
-TYPE
-   { Word to bytes}
-   WordRec = packed RECORD
-     Lo, Hi: Byte;     
-   END;
-
-   { LongInt to words }
-   LongRec = packed RECORD
-     Lo, Hi: Word;
-   END;
-
-  { Pointer to words }
-   PtrRec = packed RECORD
-     Ofs, Seg: Word;
-   END;
-\end{verbatim}
-
-The following record is used when streaming objects:
-
-\begin{verbatim}
-TYPE
-   PStreamRec = ^TStreamRec;
-   TStreamRec = Packed RECORD
-      ObjType: Sw_Word;
-      VmtLink: pointer;
-      Load : Pointer;
-      Store: Pointer;
-      Next : PStreamRec;
-   END;
-\end{verbatim}
-
-The \var{TPoint} basic object is used in the \var{TRect} object (see
-\sees{TRect}):
-\begin{verbatim}
-TYPE
-   PPoint = ^TPoint;
-   TPoint = OBJECT
-      X, Y: Sw_Integer;
-   END;
-\end{verbatim}
-
-\section{Procedures and Functions}
-
-\begin{function}{NewStr}
-\Declaration
-Function NewStr (Const S: String): PString;
-\Description
-\var{NewStr} makes a copy of the string \var{S} on the heap,
-and returns a pointer to this copy.
-
-The allocated memory is not based on the declared size of the string passed
-to \var{NewStr}, but is baed on the actual length of the string.
-\Errors
-If not enough memory is available, an 'out of memory' error will occur.
-\SeeAlso
-\seep{DisposeStr}
-\end{function}
-
-\FPCexample{ex40}
-
-\begin{procedure}{DisposeStr}
-\Declaration
-Procedure DisposeStr (P: PString);
-\Description
-\var{DisposeStr} removes a dynamically allocated string from the heap.
-\Errors
-None.
-\SeeAlso
-\seef{NewStr}
-\end{procedure}
-
-For an example, see \seef{NewStr}.
-
-\begin{procedure}{Abstract}
-\Declaration
-Procedure Abstract;
-\Description
-When implementing abstract methods, do not declare them as \var{abstract}.
-Instead, define them simply as \var{virtual}. In the implementation of such
-abstract methods, call the \var{Abstract} procedure. This allows explicit
-control of what happens when an abstract method is called.
-
-The current implementation of \var{Abstract} terminates the program with 
-a run-time error 211.
-\Errors
-None.
-\SeeAlso Most abstract types.
-\end{procedure}
-
-\begin{procedure}{RegisterObjects}
-\Declaration
-Procedure RegisterObjects;
-\Description
-\var{RegisterObjects} registers the following objects for streaming:
-\begin{enumerate}
-\item \var{TCollection}, see \sees{TCollection}.
-\item \var{TStringCollection}, see \sees{TStringCollection}.
-\item \var{TStrCollection}, see \sees{TStrCollection}.
-\end{enumerate}
-\Errors
-None.
-\SeeAlso
-\seep{RegisterType}
-\end{procedure}
-
-\begin{procedure}{RegisterType}
-\Declaration
-Procedure RegisterType (Var S: TStreamRec);
-\Description
-\var{RegisterType} registers a new type for streaming. An object cannot
-be streamed unless it has been registered first. 
-The stream record \var{S} needs to have the following fields set:
-
-\begin{description}
-\item[ObjType: Sw\_Word] This should be a unique identifier. Each possible
-type should have it's own identifier. 
-\item[VmtLink: pointer] This should contain a pointer to the VMT (Virtual
-Method Table) of the object you try to register. You can get it with the
-following expression:
-\begin{verbatim}
-     VmtLink: Ofs(TypeOf(MyType)^);
-\end{verbatim}
-\item[Load : Pointer] is a pointer to a method that initializes an instance
-of that object, and reads the initial values from a stream. This method
-should accept as it's sole argument a \var{PStream} type variable.
-\item[Store: Pointer]is a pointer to a method that stores an instance of the
-object to a stream. This method should accept as it's sole argument
- a \var{PStream} type variable.
-\end{description}
-\Errors
-In case of error (if a object with the same \var{ObjType}) is already
-registered), run-time error 212 occurs.
-\end{procedure}
-
-\FPCexample{myobject}
-
-\begin{function}{LongMul}
-\Declaration
-Function LongMul (X, Y: Integer): LongInt;
-\Description
-\var{LongMul} multiplies \var{X} with \var{Y}. The result is of
-type \var{Longint}. This avoids possible overflow errors you would normally
-get when multiplying \var{X} and \var{Y} that are too big.
-\Errors
-None.
-\SeeAlso
-\seef{LongDiv}
-\end{function}
-
-\begin{function}{LongDiv}
-\Declaration
-Function LongDiv (X: Longint; Y: Integer): Integer;
-\Description
-\var{LongDiv} divides \var{X} by \var{Y}. The result is of
-type \var{Integer} instead of type \var{Longint}, as you would get 
-normally. 
-\Errors
-If Y is zero, a run-time error will be generated.
-\SeeAlso
-\seef{LongMul}
-\end{function}
-
-\section{TRect}
-\label{se:TRect}
-
-The \var{TRect} object is declared as follows:
-\begin{verbatim}
-   TRect = OBJECT
-      A, B: TPoint;
-      FUNCTION Empty: Boolean;
-      FUNCTION Equals (R: TRect): Boolean;
-      FUNCTION Contains (P: TPoint): Boolean;
-      PROCEDURE Copy (R: TRect);
-      PROCEDURE Union (R: TRect);
-      PROCEDURE Intersect (R: TRect);
-      PROCEDURE Move (ADX, ADY: Sw_Integer);
-      PROCEDURE Grow (ADX, ADY: Sw_Integer);
-      PROCEDURE Assign (XA, YA, XB, YB: Sw_Integer);
-   END;
-\end{verbatim}
-
-\begin{function}{TRect.Empty}
-\Declaration
-Function TRect.Empty: Boolean;
-\Description
-\var{Empty} returns \var{True} if the rectangle defined by the corner points 
-\var{A}, \var{B} has zero or negative surface.
-\Errors
-None.
-\SeeAlso
-\seef{TRect.Equals}, \seef{TRect.Contains}
-\end{function}
-
-\FPCexample{ex1}
-
-\begin{function}{TRect.Equals}      
-\Declaration
-Function TRect.Equals (R: TRect): Boolean;
-\Description
-\var{Equals} returns \var{True} if the rectangle has the 
-same corner points \var{A,B} as the rectangle R, and \var{False}
-otherwise.
-\Errors
-None.
-\SeeAlso
-\seefl{Empty}{TRect.Empty}, \seefl{Contains}{TRect.Contains}
-\end{function}
-
-For an example, see \seef{TRect.Empty}
-
-\begin{function}{TRect.Contains}
-\Declaration
-Function TRect.Contains (P: TPoint): Boolean;
-\Description
-\var{Contains} returns \var{True} if the point \var{P} is contained
-in the rectangle (including borders), \var{False} otherwise.
-\Errors
-None.
-\SeeAlso
-\seepl{Intersect}{TRect.Intersect}, \seefl{Equals}{TRect.Equals}
-\end{function}
-
-\begin{procedure}{TRect.Copy}
-\Declaration     
-Procedure TRect.Copy (R: TRect);
-\Description
-Assigns the rectangle R to the object. After the call to \var{Copy}, the
-rectangle R has been copied to the object that invoked \var{Copy}.
-\Errors
-None.
-\SeeAlso
-\seepl{Assign}{TRect.Assign}
-\end{procedure}
-
-\FPCexample{ex2}
-
-\begin{procedure}{TRect.Union}
-\Declaration
-Procedure TRect.Union (R: TRect);
-\Description
-\var{Union} enlarges the current rectangle so that it becomes the union
-of the current rectangle with the rectangle \var{R}.
-\Errors
-None.
-\SeeAlso
-\seepl{Intersect}{TRect.Intersect}
-\end{procedure}
-
-\FPCexample{ex3}
-
-\begin{procedure}{TRect.Intersect}
-\Declaration
-Procedure TRect.Intersect (R: TRect);
-\Description
-\var{Intersect} makes the intersection of the current rectangle with
-\var{R}. If the intersection is empty, then the rectangle is set to the empty
-rectangle at coordinate (0,0).
-\Errors
-None.
-\SeeAlso
-\seepl{Union}{TRect.Union}
-\end{procedure}
-
-\FPCexample{ex4}
-
-\begin{procedure}{TRect.Move}
-\Declaration
-Procedure TRect.Move (ADX, ADY: Sw\_Integer);
-\Description
-\var{Move} moves the current rectangle along a vector with components
-\var{(ADX,ADY)}. It adds \var{ADX} to the X-coordinate of both corner
-points, and \var{ADY} to both end points.
-\Errors
-None.
-\SeeAlso
-\seepl{Grow}{TRect.Grow}
-\end{procedure}
-
-\FPCexample{ex5}
-
-\begin{procedure}{TRect.Grow}
-\Declaration
-Procedure TRect.Grow (ADX, ADY: Sw\_Integer);
-\Description
-\var{Grow} expands the rectangle with an amount \var{ADX} in the \var{X}
-direction (both on the left and right side of the rectangle, thus adding a 
-length 2*ADX to the width of the rectangle), and an amount \var{ADY} in 
-the \var{Y} direction (both on the top and the bottom side of the rectangle,
-adding a length 2*ADY to the height of the rectangle. 
-
-\var{ADX} and \var{ADY} can be negative. If the resulting rectangle is empty, it is set 
-to the empty rectangle at \var{(0,0)}.
-\Errors
-None.
-\SeeAlso
-\seepl{Move}{TRect.Move}.
-\end{procedure}
-
-
-\FPCexample{ex6}
-
-\begin{procedure}{TRect.Assign}
-\Declaration
-Procedure Trect.Assign (XA, YA, XB, YB: Sw\_Integer);
-\Description
-\var{Assign} sets the corner points of the rectangle to \var{(XA,YA)} and 
-\var{(Xb,Yb)}.
-\Errors
-None.
-\SeeAlso
-\seepl{Copy}{TRect.Copy}
-\end{procedure}
-
-For an example, see \seep{TRect.Copy}.
-
-\section{TObject}
-\label{se:TObject}
-
-The full declaration of the \var{TObject} type is:
-\begin{verbatim}
-TYPE
-   TObject = OBJECT
-      CONSTRUCTOR Init;
-      PROCEDURE Free;
-      DESTRUCTOR Done;Virtual;
-   END;
-   PObject = ^TObject;
-\end{verbatim}
-\begin{procedure}{TObject.Init}
-\Declaration
-Constructor TObject.Init;
-\Description
-Instantiates a new object of type \var{TObject}. It fills the instance up
-with Zero bytes.
-\Errors
-None.
-\SeeAlso
-\seepl{Free}{TObject.Free}, \seepl{Done}{TObject.Done}
-\end{procedure}
-
-For an example, see \seepl{Free}{TObject.Free}
-
-\begin{procedure}{TObject.Free}
-\Declaration
-Procedure TObject.Free;
-\Description
-\var{Free} calls the destructor of the object, and releases the memory
-occupied by the instance of the object.
-\Errors
-No checking is performed to see whether \var{self} is \var{nil} and whether
-the object is indeed allocated on the heap.
-\SeeAlso
-\seepl{Init}{TObject.Init}, \seepl{Done}{TObject.Done}
-\end{procedure}
-
-\FPCexample{ex7}
-
-\begin{procedure}{TObject.Done}
-\Declaration
-Destructor TObject.Done;Virtual;
-\Description
-\var{Done}, the destructor of \var{TObject} does nothing. It is mainly
-intended to be used in the \seep{TObject.Free} method.
-
-The destructore Done does not free the memory occupied by the object.
-\Errors
-None.
-\SeeAlso
-\seepl{Free}{TObject.Free}, \seepl{Init}{TObject.Init}
-\end{procedure}
-
-\FPCexample{ex8}
-
-\section{TStream}
-\label{se:TStream}
-
-The \var{TStream} object is the ancestor for all streaming objects, i.e.
-objects that have the capability to store and retrieve data.
-
-It defines a number of methods that are common to all objects that implement
-streaming, many of them are virtual, and are only implemented in the
-descendrnt types.
-
-Programs should not instantiate objects of type TStream directly, but
-instead instantiate a descendant type, such as \var{TDosStream},
-\var{TMemoryStream}.
-
-This is the full declaration of the \var{TStream} object:
-\begin{verbatim}
-TYPE
-   TStream = OBJECT (TObject)
-         Status    : Integer; { Stream status }
-         ErrorInfo : Integer; { Stream error info }
-         StreamSize: LongInt; { Stream current size }
-         Position  : LongInt; { Current position }
-      FUNCTION Get: PObject;
-      FUNCTION StrRead: PChar;
-      FUNCTION GetPos: Longint; Virtual;
-      FUNCTION GetSize: Longint; Virtual;
-      FUNCTION ReadStr: PString;
-      PROCEDURE Open (OpenMode: Word); Virtual;
-      PROCEDURE Close; Virtual;
-      PROCEDURE Reset;
-      PROCEDURE Flush; Virtual;
-      PROCEDURE Truncate; Virtual;
-      PROCEDURE Put (P: PObject);
-      PROCEDURE StrWrite (P: PChar);
-      PROCEDURE WriteStr (P: PString);
-      PROCEDURE Seek (Pos: LongInt); Virtual;
-      PROCEDURE Error (Code, Info: Integer); Virtual;
-      PROCEDURE Read (Var Buf; Count: Sw_Word); Virtual;
-      PROCEDURE Write (Var Buf; Count: Sw_Word); Virtual;
-      PROCEDURE CopyFrom (Var S: TStream; Count: Longint);
-   END;
-   PStream = ^TStream;
-\end{verbatim}
-
-\begin{function}{TStream.Get}
-\Declaration
-Function TStream.Get : PObject;
-\Description
-\var{Get} reads an object definition  from a stream, and returns
-a pointer to an instance of this object.
-\Errors
-On error, \var{TStream.Status} is set, and NIL is returned.
-\SeeAlso 
-\seepl{Put}{TStream.Put}
-\end{function}
-
-\FPCexample{ex9}
-
-\begin{function}{TStream.StrRead}
-\Declaration
-Function TStream.StrRead: PChar;
-\Description
-\var{StrRead} reads a string from the stream, allocates memory
-for it, and returns a pointer to a null-terminated copy of the string
-on the heap.
-\Errors
-On error, \var{Nil} is returned.
-\SeeAlso
-\seepl{StrWrite}{TStream.StrWrite}, \seefl{ReadStr}{TStream.ReadStr}
-\end{function}
-
-\FPCexample{ex10}
-
-
-\begin{function}{TStream.GetPos}
-\Declaration 
-TSTream.GetPos : Longint; Virtual;
-\Description
-If the stream's status is \var{stOk}, \var{GetPos} returns the current 
-position in the stream. Otherwise it returns \var{-1}
-\Errors
-\var{-1} is returned if the status is an error condition.
-\SeeAlso
-\seepl{Seek}{TStream.Seek}, \seefl{GetSize}{TStream.GetSize}
-\end{function}
-
-\FPCexample{ex11}
-
-
-\begin{function}{TStream.GetSize}
-\Declaration
-Function TStream.GetSize: Longint; Virtual;
-\Description
-If the stream's status is \var{stOk} then \var{GetSize} returns
-the size of the stream, otherwise it returns \var{-1}.
-\Errors
-\var{-1} is returned if the status is an error condition.
-\SeeAlso
-\seepl{Seek}{TStream.Seek}, \seefl{GetPos}{TStream.GetPos}
-\end{function}
-
-\FPCexample{ex12}
-
-
-\begin{function}{TStream.ReadStr}
-\Declaration
-Function TStream.ReadStr: PString;
-\Description
-\var{ReadStr} reads a string from the stream, copies it to the heap
-and returns a pointer to this copy. The string is saved as a pascal
-string, and hence is NOT null terminated.
-\Errors
-On error (e.g. not enough memory), \var{Nil} is returned.
-\SeeAlso
-\seefl{StrRead}{TStream.StrRead}
-\end{function}
-
-\FPCexample{ex13}
-
-
-\begin{procedure}{TStream.Open}
-\Declaration
-Procedure TStream.Open (OpenMode: Word); Virtual;
-\Description
-\var{Open} is an abstract method, that should be overridden by descendent
-objects. Since opening a stream depends on the stream's type this is not
-surprising.
-\Errors
-None.
-\SeeAlso
-\seepl{Close}{TStream.Close}, \seepl{Reset}{TStream.Reset}
-\end{procedure}
-
-For an example, see \seep{TDosStream.Open}.
-
-\begin{procedure}{TStream.Close}
-\Declaration
-Procedure TStream.Close; Virtual;
-\Description
-\var{Close} is an abstract method, that should be overridden by descendent
-objects. Since Closing a stream depends on the stream's type this is not
-surprising.
-\Errors
-None.
-\SeeAlso
-\seepl{Open}{TStream.Open}, \seepl{Reset}{TStream.Reset}
-\end{procedure}
-
-for an example, see \seep{TDosStream.Open}.
-
-\begin{procedure}{TStream.Reset}
-\Declaration
-PROCEDURE TStream.Reset;
-\Description
-\var{Reset} sets the stream's status to \var{0}, as well as the ErrorInfo
-\Errors
-None.
-\SeeAlso
-\seepl{Open}{TStream.Open}, \seepl{Close}{TStream.Close}
-\end{procedure}
-
-\begin{procedure}{TStream.Flush}
-\Declaration 
-Procedure TStream.Flush; Virtual;
-\Description
-\var{Flush} is an abstract method that should be overridden by descendent
-objects. It serves to enable the programmer to tell streams that implement 
-a buffer to clear the buffer.
-\Errors
-None.
-\SeeAlso
-\seepl{Truncate}{TStream.Truncate}
-\end{procedure}
-
-for an example, see \seep{TBufStream.Flush}.
-
-\begin{procedure}{TStream.Truncate}
-\Declaration
-Procedure TStream.Truncate; Virtual;
-\Description
-\var{Truncate} is an abstract procedure that should be overridden by
-descendent objects. It serves to enable the programmer to truncate the
-size of the stream to the current file position.
-\Errors
-None.
-\SeeAlso
-\seepl{Seek}{TStream.Seek}
-\end{procedure}
-
-For an example, see \seep{TDosStream.Truncate}.
-
-\begin{procedure}{TStream.Put}
-\Declaration
-Procedure TStream.Put (P: PObject);
-\Description
-\var{Put} writes the object pointed to by \var{P}. \var{P} should be
-non-nil. The object type must have been registered with \seep{RegisterType}.
-
-After the object has been written, it can be read again with \seefl{Get}{TStream.Get}.
-\Errors
-No check is done whether P is \var{Nil} or not. Passing \var{Nil} will cause
-a run-time error 216 to be generated. If the object has not been registered,
-the status of the stream will be set to \var{stPutError}.
-\SeeAlso
-\seefl{Get}{TStream.Get}
-\end{procedure}
-
-For an example, see \seef{TStream.Get};
-
-\begin{procedure}{TStream.StrWrite}
-\Declaration
-Procedure TStream.StrWrite (P: PChar);
-\Description
-\var{StrWrite} writes the null-terminated string \var{P} to the stream.
-\var{P} can only be 65355 bytes long.
-\Errors
-None.
-\SeeAlso
-\seepl{WriteStr}{TStream.WriteStr}, \seefl{StrRead}{TStream.StrRead},
-\seefl{ReadStr}{TStream.ReadStr}
-\end{procedure}
-
-For an example, see \seef{TStream.StrRead}.
-
-\begin{procedure}{TStream.WriteStr}
-\Declaration
-Procedure TStream.WriteStr (P: PString);
-\Description
-\var{StrWrite} writes the pascal string pointed to by \var{P} to the stream.
-\Errors
-None.
-\SeeAlso
-\seepl{StrWrite}{TStream.StrWrite}, \seefl{StrRead}{TStream.StrRead},
-\seefl{ReadStr}{TStream.ReadStr}
-\end{procedure}
-
-For an example, see \seef{TStream.ReadStr}.
-
-\begin{procedure}{TStream.Seek}
-\Declaration      
-PROCEDURE TStream.Seek (Pos: LongInt); Virtual;
-\Description
-Seek sets the position to \var{Pos}. This position is counted
-from the beginning, and is zero based. (i.e. seeek(0) sets the position
-pointer on the first byte of the stream)
-\Errors
-If \var{Pos} is larger than the stream size, \var{Status} is set to
-\var{StSeekError}.
-\SeeAlso
-\seefl{GetPos}{TStream.GetPos}, \seefl{GetSize}{TStream.GetSize}
-\end{procedure}
-
-
-For an example, see \seep{TDosStream.Seek}.
-
-\begin{procedure}{TStream.Error}
-\Declaration
-Procedure TStream.Error (Code, Info: Integer); Virtual;
-\Description
-\var{Error} sets the stream's status to \var{Code} and \var{ErrorInfo}
-to \var{Info}. If the \var{StreamError} procedural variable is set,
-\var{Error} executes it, passing \var{Self} as an argument.
-
-This method should not be called directly from a program. It is intended to
-be used in descendent objects.
-\Errors
-None.
-\SeeAlso
-\end{procedure}
-
-\begin{procedure}{TStream.Read}
-\Declaration
-Procedure TStream.Read (Var Buf; Count: Sw\_Word); Virtual;
-\Description
-\var{Read} is an abstract method that should be overridden by descendent
-objects.
-
-\var{Read} reads \var{Count} bytes from the stream into \var{Buf}.
-It updates the position pointer, increasing it's value with \var{Count}. 
-\var{Buf} must be large enough to contain \var{Count} bytes.
-\Errors
-No checking is done to see if \var{Buf} is large enough to contain
-\var{Count} bytes. 
-\SeeAlso
-\seepl{Write}{TStream.Write}, \seefl{ReadStr}{TStream.ReadStr},
-\seefl{StrRead}{TStream.StrRead}
-\end{procedure}
-
-\FPCexample{ex18}
-
-
-\begin{procedure}{TStream.Write}
-\Declaration
-Procedure TStream.Write (Var Buf; Count: Sw\_Word); Virtual;
-\Description
-\var{Write} is an abstract method that should be overridden by descendent
-objects.
-
-\var{Write} writes \var{Count} bytes to the stream from \var{Buf}.
-It updates the position pointer, increasing it's value with \var{Count}. 
-\Errors
-No checking is done to see if \var{Buf} actually contains \var{Count} bytes. 
-\SeeAlso
-\seepl{Read}{TStream.Read}, \seepl{WriteStr}{TStream.WriteStr},
-\seepl{StrWrite}{TStream.StrWrite}
-\end{procedure}
-
-For an example, see \seep{TStream.Read}.
-
-\begin{procedure}{TStream.CopyFrom}
-\Declaration
-Procedure TStream.CopyFrom (Var S: TStream; Count: Longint);
-\Description
-\var{CopyFrom} reads Count bytes from stream \var{S} and stores them
-in the current stream. It uses the \seepl{Read}{TStream.Read} method
-to read the data, and the \seepl{Write}{TStream.Write} method to
-write in the current stream.
-\Errors
-None.
-\SeeAlso
-\seepl{Read}{TStream.Read}, \seepl{Write}{TStream.Write}
-\end{procedure}
-
-\FPCexample{ex19}
-
-
-\section{TDosStream}
-\label{se:TDosStream}
-
-\var{TDosStream} is a stream that stores it's contents in a file.
-it overrides a couple of methods of \var{TSteam} for this.
-
-In addition to the fields inherited from \var{TStream} (see \sees{TStream}),
-there are some extra fields, that describe the file. (mainly the name and
-the OS file handle)
-
-No buffering in memory is done when using \var{TDosStream}. 
-All data are written directly to the file. For a stream that buffers 
-in memory, see \sees{TBufStream}.
-
-Here is the full declaration of the \var{TDosStream} object:
-\begin{verbatim}
-TYPE
-   TDosStream = OBJECT (TStream)
-         Handle: THandle; { DOS file handle }
-         FName : AsciiZ;  { AsciiZ filename }
-      CONSTRUCTOR Init (FileName: FNameStr; Mode: Word);
-      DESTRUCTOR Done; Virtual;
-      PROCEDURE Close; Virtual;
-      PROCEDURE Truncate; Virtual;
-      PROCEDURE Seek (Pos: LongInt); Virtual;
-      PROCEDURE Open (OpenMode: Word); Virtual;
-      PROCEDURE Read (Var Buf; Count: Sw_Word); Virtual;
-      PROCEDURE Write (Var Buf; Count: Sw_Word); Virtual;
-   END;
-   PDosStream = ^TDosStream;
-\end{verbatim}
-
-\begin{procedure}{TDosStream.Init}
-\Declaration
-Constructor Init (FileName: FNameStr; Mode: Word);
-\Description
-\var{Init} instantiates an instance of \var{TDosStream}. The name of the 
-file that contains (or will contain) the data of the stream is given in
-\var{FileName}. The \var{Mode} parameter determines whether a new file 
-should be created and what access rights you have on the file. 
-It can be one of the following constants:
-\begin{description}
-\item[stCreate] Creates a new file.
-\item[stOpenRead] Read access only.
-\item[stOpenWrite] Write access only.
-\item[stOpen] Read and write access.
-\end{description}
-\Errors
-On error, \var{Status} is set to \var{stInitError}, and \var{ErrorInfo}
-is set to the \dos error code.
-\SeeAlso
-\seepl{Done}{TDosStream.Done}
-\end{procedure}
-
-For an example, see \seep{TDosStream.Truncate}.
-
-\begin{procedure}{TDosStream.Done}
-\Declaration
-Destructor TDosStream.Done; Virtual;
-\Description
-\var{Done} closes the file if it was open and cleans up the 
-instance of \var{TDosStream}. 
-\Errors
-None.
-\SeeAlso
-\seepl{Init}{TDosStream.Init},
-\seepl{Close}{TDosStream.Close}
-\end{procedure}
-
-for an example, see e.g. \seep{TDosStream.Truncate}.
-
-\begin{procedure}{TDosStream.Close}
-\Declaration
-Pocedure TDosStream.Close; Virtual;
-\Description
-\var{Close} closes the file if it was open, and sets \var{Handle} to -1. 
-Contrary to \seepl{Done}{TDosStream.Done} it does not clean up the instance
-of \var{TDosStream}
-\Errors
-None.
-\SeeAlso
-\seep{TStream.Close}, \seepl{Init}{TDosStream.Init},
-\seepl{Done}{TDosStream.Done}
-\end{procedure}
-
-For an example, see \seep{TDosStream.Open}.
-
-\begin{procedure}{TDosStream.Truncate}
-\Declaration
-Procedure TDosStream.Truncate; Virtual;
-\Description
-If the status of the stream is \var{stOK}, then \var{Truncate} tries to
-truncate the stream size to the current file position.
-\Errors
-If an error occurs, the stream's status is set to \var{stError} and
-\var{ErrorInfo} is set to the OS error code.
-\SeeAlso
-\seep{TStream.Truncate}, \seefl{GetSize}{TStream.GetSize}
-\end{procedure}
-
-\FPCexample{ex16}
-
-
-\begin{procedure}{TDosStream.Seek}
-\Declaration
-Procedure TDosStream.Seek (Pos: LongInt); Virtual;
-\Description
-If the stream's status is \var{stOK}, then \var{Seek} sets the 
-file position to \var{Pos}. \var{Pos} is a zero-based offset, counted from
-the beginning of the file.
-\Errors
-In case an error occurs, the stream's status is set to \var{stSeekError},
-and the OS error code is stored in \var{ErrorInfo}.
-\SeeAlso
-\seep{TStream.Seek}, \seefl{GetPos}{TStream.GetPos}
-\end{procedure}
-
-\FPCexample{ex17}
-
-
-\begin{procedure}{TDosStream.Open}
-\Declaration
-Procedure TDosStream.Open (OpenMode: Word); Virtual;
-\Description
-If the stream's status is \var{stOK}, and the stream is closed then
-\var{Open} re-opens the file stream with mode \var{OpenMode}.
-This call can be used after a \seepl{Close}{TDosStream.Close} call.
-\Errors
-If an error occurs when re-opening the file, then \var{Status} is set
-to \var{stOpenError}, and the OS error code is stored in \var{ErrorInfo}
-\SeeAlso
-\seep{TStream.Open}, \seepl{Close}{TDosStream.Close}
-\end{procedure}
-
-\FPCexample{ex14}
-
-
-\begin{procedure}{TDosStream.Read}
-\Declaration
-Procedure TDosStream.Read (Var Buf; Count: Sw\_Word); Virtual;
-\Description
-If the Stream is open and the stream status is \var{stOK} then 
-\var{Read} will read \var{Count} bytes from the stream and place them
-in  \var{Buf}.
-\Errors
-In case of an error, \var{Status} is set to \var{StReadError}, and
-\var{ErrorInfo} gets the OS specific error, or 0 when an attempt was
-made to read beyond the end of the stream.
-\SeeAlso
-\seep{TStream.Read}, \seepl{Write}{TDosStream.Write}
-\end{procedure}
-
-For an example, see \seep{TStream.Read}.
-
-\begin{procedure}{TDosStream.Write}
-\Declaration
-Procedure TDosStream.Write (Var Buf; Count: Sw\_Word); Virtual;
-\Description
-If the Stream is open and the stream status is \var{stOK} then 
-\var{Write} will write \var{Count} bytes from \var{Buf} and place them
-in the stream.
-\Errors
-In case of an error, \var{Status} is set to \var{StWriteError}, and
-\var{ErrorInfo} gets the OS specific error.
-\SeeAlso
-\seep{TStream.Write}, \seepl{Read}{TDosStream.Read}
-\end{procedure}
-
-For an example, see \seep{TStream.Read}.
-
-\section{TBufStream}
-\label{se:TBufStream}
-
-\var{Bufstream} implements a buffered file stream. That is, all data written
-to the stream is written to memory first. Only when the buffer is full, or
-on explicit request, the data is written to disk.
-
-Also, when reading from the stream, first the buffer is checked if there is
-any unread data in it. If so, this is read first. If not the buffer is
-filled again, and then the data is read from the buffer.
-
-The size of the buffer is fixed and is set when constructing the file.
-
-This is useful if you need heavy throughput for your stream, because it
-speeds up operations.
-
-\begin{verbatim}
-TYPE
-   TBufStream = OBJECT (TDosStream)
-         LastMode: Byte;       { Last buffer mode }
-         BufSize : Sw_Word;    { Buffer size }
-         BufPtr  : Sw_Word;    { Buffer start }
-         BufEnd  : Sw_Word;    { Buffer end }
-         Buffer  : PByteArray; { Buffer allocated }
-      CONSTRUCTOR Init (FileName: FNameStr; Mode, Size: Word);
-      DESTRUCTOR Done; Virtual;
-      PROCEDURE Close; Virtual;
-      PROCEDURE Flush; Virtual;
-      PROCEDURE Truncate; Virtual;
-      PROCEDURE Seek (Pos: LongInt); Virtual;
-      PROCEDURE Open (OpenMode: Word); Virtual;
-      PROCEDURE Read (Var Buf; Count: Sw_Word); Virtual;
-      PROCEDURE Write (Var Buf; Count: Sw_Word); Virtual;
-   END;
-   PBufStream = ^TBufStream;
-\end{verbatim}
-
-\begin{procedure}{TBufStream.Init}
-\Declaration
-Constructor Init (FileName: FNameStr; Mode,Size: Word);
-\Description
-\var{Init} instantiates an instance of \var{TBufStream}. The name of the 
-file that contains (or will contain) the data of the stream is given in
-\var{FileName}. The \var{Mode} parameter determines whether a new file 
-should be created and what access rights you have on the file. 
-It can be one of the following constants:
-\begin{description}
-\item[stCreate] Creates a new file.
-\item[stOpenRead] Read access only.
-\item[stOpenWrite] Write access only.
-\item[stOpen] Read and write access.
-\end{description}
-The \var{Size} parameter determines the size of the buffer that will be
-created. It should be different from zero.
-\Errors
-On error, \var{Status} is set to \var{stInitError}, and \var{ErrorInfo}
-is set to the \dos error code.
-\SeeAlso
-\seep{TDosStream.Init}, \seepl{Done}{TBufStream.Done}
-\end{procedure}
-
-For an example see \seep{TBufStream.Flush}.
-
-\begin{procedure}{TBufStream.Done}
-\Declaration
-Destructor TBufStream.Done; Virtual;
-\Description
-\var{Done} flushes and closes the file if it was open and cleans up the 
-instance of \var{TBufStream}. 
-\Errors
-None.
-\SeeAlso
-\seep{TDosStream.Done}, \seepl{Init}{TBufStream.Init},
-\seepl{Close}{TBufStream.Close}
-\end{procedure}
-
-For an example see \seep{TBufStream.Flush}.
-
-\begin{procedure}{TBufStream.Close}
-\Declaration
-Pocedure TBufStream.Close; Virtual;
-\Description
-\var{Close} flushes and closes the file if it was open, and sets \var{Handle} to -1. 
-Contrary to \seepl{Done}{TBufStream.Done} it does not clean up the instance
-of \var{TBufStream}
-\Errors
-None.
-\SeeAlso
-\seep{TStream.Close}, \seepl{Init}{TBufStream.Init},
-\seepl{Done}{TBufStream.Done}
-\end{procedure}
-
-For an example see \seep{TBufStream.Flush}.
-
-\begin{procedure}{TBufStream.Flush}
-\Declaration
-Pocedure TBufStream.Flush; Virtual;
-\Description
-When the stream is in write mode, the contents of the buffer are written to
-disk, and the buffer position is set to zero.
-
-When the stream is in read mode, the buffer position is set to zero.
-\Errors
-Write errors may occur if the file was in write mode.
-see \seepl{Write}{TBufStream.Write} for more info on the errors.
-\SeeAlso
-\seep{TStream.Close}, \seepl{Init}{TBufStream.Init},
-\seepl{Done}{TBufStream.Done}
-\end{procedure}
-
-\FPCexample{ex15}
-
-
-\begin{procedure}{TBufStream.Truncate}
-\Declaration
-Procedure TBufStream.Truncate; Virtual;
-\Description
-If the status of the stream is \var{stOK}, then \var{Truncate} tries to
-flush the buffer, and then truncates the stream size to the current 
-file position.
-\Errors
-Errors can be those of \seepl{Flush}{TBufStream.Flush} or
-\seep{TDosStream.Truncate}.
-\SeeAlso
-\seep{TStream.Truncate}, \seep{TDosStream.Truncate},
-\seefl{GetSize}{TStream.GetSize}
-\end{procedure}
-
-For an example, see \seep{TDosStream.Truncate}.
-
-\begin{procedure}{TBufStream.Seek}
-\Declaration
-Procedure TBufStream.Seek (Pos: LongInt); Virtual;
-\Description
-If the stream's status is \var{stOK}, then \var{Seek} sets the 
-file position to \var{Pos}. \var{Pos} is a zero-based offset, counted from
-the beginning of the file.
-\Errors
-In case an error occurs, the stream's status is set to \var{stSeekError},
-and the OS error code is stored in \var{ErrorInfo}.
-\SeeAlso
-\seep{TStream.Seek}, \seefl{GetPos}{TStream.GetPos}
-\end{procedure}
-
-For an example, see \seep{TStream.Seek};
-
-\begin{procedure}{TBufStream.Open}
-\Declaration
-Procedure TBufStream.Open (OpenMode: Word); Virtual;
-\Description
-If the stream's status is \var{stOK}, and the stream is closed then
-\var{Open} re-opens the file stream with mode \var{OpenMode}.
-This call can be used after a \seepl{Close}{TBufStream.Close} call.
-\Errors
-If an error occurs when re-opening the file, then \var{Status} is set
-to \var{stOpenError}, and the OS error code is stored in \var{ErrorInfo}
-\SeeAlso
-\seep{TStream.Open}, \seepl{Close}{TBufStream.Close}
-\end{procedure}
-
-For an example, see \seep{TDosStream.Open}.
-
-\begin{procedure}{TBufStream.Read}
-\Declaration
-Procedure TBufStream.Read (Var Buf; Count: Sw\_Word); Virtual;
-\Description
-If the Stream is open and the stream status is \var{stOK} then 
-\var{Read} will read \var{Count} bytes from the stream and place them
-in  \var{Buf}.
-
-\var{Read} will first try to read the data from the stream's internal
-buffer. If insufficient data is available, the buffer will be filled before
-contiunuing to read. This process is repeated until all needed data 
-has been read.
-
-\Errors
-In case of an error, \var{Status} is set to \var{StReadError}, and
-\var{ErrorInfo} gets the OS specific error, or 0 when an attempt was
-made to read beyond the end of the stream.
-\SeeAlso
-\seep{TStream.Read}, \seepl{Write}{TBufStream.Write}
-\end{procedure}
-
-For an example, see \seep{TStream.Read}.
-
-\begin{procedure}{TBufStream.Write}
-\Declaration
-Procedure TBufStream.Write (Var Buf; Count: Sw\_Word); Virtual;
-\Description
-If the Stream is open and the stream status is \var{stOK} then 
-\var{Write} will write \var{Count} bytes from \var{Buf} and place them
-in the stream.
-
-\var{Write} will first try to write the data to the stream's internal
-buffer. When the internal buffer is full, then the contents will be written 
-to disk. This process is repeated until all data has been written.
-\Errors
-In case of an error, \var{Status} is set to \var{StWriteError}, and
-\var{ErrorInfo} gets the OS specific error.
-\SeeAlso
-\seep{TStream.Write}, \seepl{Read}{TBufStream.Read}
-\end{procedure}
-
-For an example, see \seep{TStream.Read}.
-
-\section{TMemoryStream}
-\label{se:TMemoryStream}
-
-The \var{TMemoryStream} object implements a stream that stores it's data
-in memory. The data is stored on the heap, with the possibility to specify
-the maximum amout of data, and the the size of the memory blocks being used.
- 
-\begin{verbatim}
-TYPE
-   TMemoryStream = OBJECT (TStream)
-         BlkCount: Sw_Word;       { Number of segments }
-         BlkSize : Word;          { Memory block size  }
-         MemSize : LongInt;       { Memory alloc size  }
-         BlkList : PPointerArray; { Memory block list  }
-      CONSTRUCTOR Init (ALimit: Longint; ABlockSize: Word);
-      DESTRUCTOR Done;                                               Virtual;
-      PROCEDURE Truncate;                                            Virtual;
-      PROCEDURE Read (Var Buf; Count: Sw_Word);                      Virtual;
-      PROCEDURE Write (Var Buf; Count: Sw_Word);                     Virtual;
-   END;
-   PMemoryStream = ^TMemoryStream;
-\end{verbatim}
-
-\begin{procedure}{TMemoryStream.Init}
-\Declaration
-Constructor TMemoryStream.Init (ALimit: Longint; ABlockSize: Word);
-\Description
-\var{Init} instantiates a new \var{TMemoryStream} object. The
-memorystreamobject will initially allocate at least \var{ALimit} bytes memory, 
-divided into memory blocks of size \var{ABlockSize}. 
-The number of blocks needed to get to \var{ALimit} bytes is rounded up.
-
-By default, the number of blocks is 1, and the size of a block is 8192. This
-is selected if you specify 0 as the blocksize.
-\Errors
-If the stream cannot allocate the initial memory needed for the memory blocks, then
-the stream's status is set to \var{stInitError}.
-\SeeAlso
-\seepl{Done}{TMemoryStream.Done}
-\end{procedure}
-
-For an example, see e.g \seep{TStream.CopyFrom}.
-
-\begin{procedure}{TMemoryStream.Done}
-\Declaration
-Destructor TMemoryStream.Done; Virtual;
-\Description
-\var{Done} releases the memory blocks used by the stream, and then cleans up
-the memory used by the stream object itself.
-\Errors
-None.
-\SeeAlso
-\seepl{Init}{TMemoryStream.Init}
-\end{procedure}
-
-For an example, see e.g \seep{TStream.CopyFrom}.
-
-\begin{procedure}{TMemoryStream.Truncate}
-\Declaration
-Procedure TMemoryStream.Truncate; Virtual;
-\Description
-\var{Truncate} sets the size of the memory stream equal to the current
-position. It de-allocates any memory-blocks that are no longer needed, so
-that the new size of the stream is the current position in the stream,
-rounded up to the first multiple of the stream blocksize.
-\Errors 
-If an error occurs during memory de-allocation, the stream's status is set
-to \var{stError}
-\SeeAlso
-\seep{TStream.Truncate}
-\end{procedure}
-
-\FPCexample{ex20}
-
-
-\begin{procedure}{TMemoryStream.Read}
-\Declaration
-Procedure Read (Var Buf; Count: Sw\_Word); Virtual;
-\Description
-\var{Read} reads \var{Count} bytes from the stream to \var{Buf}. It updates
-the position of the stream.
-\Errors
-If there is not enough data available, no data is read, and the stream's
-status is set to \var{stReadError}.
-\SeeAlso
-\var{TStream.Read}, \seepl{Write}{TMemoryStream.Write}
-\end{procedure}
-
-For an example, see \seep{TStream.Read}.
-
-\begin{procedure}{TMemoryStream.Write}
-\Declaration
-Procedure Write (Var Buf; Count: Sw\_Word); Virtual;
-\Description
-\var{Write} copies \var{Count} bytes from \var{Buf} to the stream. It
-updates the position of the stream. 
-
-If not enough memory is available to hold the extra \var{Count} bytes, 
-then the stream will try to expand, by allocating as much blocks with 
-size \var{BlkSize} (as specified in the constuctor call
-\seepl{Init}{TMemoryStream.Init}) as needed. 
-\Errors
-If the stream cannot allocate more memory, then the status is set to
-\var{stWriteError}
-\SeeAlso
-\seep{TStream.Write}, \seepl{Read}{TMemoryStream.Read}
-\end{procedure}
-
-For an example, see \seep{TStream.Read}.
-
-\section{TCollection}
-\label{se:TCollection}
-
-The \var{TCollection} object manages a collection of pointers or objects. 
-It also provides a series of methods to manipulate these pointers or 
-objects.
-
-Whether or not objects are used depends on the kind of calls you use.
-ALl kinds come in 2 flavors, one for objects, one for pointers.
-
-This is the full declaration of the \var{TCollection} object:
-
-\begin{verbatim}
-TYPE
-   TItemList = Array [0..MaxCollectionSize - 1] Of Pointer;
-   PItemList = ^TItemList;
-
-   TCollection = OBJECT (TObject)
-         Items: PItemList;  { Item list pointer }
-         Count: Sw_Integer; { Item count }
-         Limit: Sw_Integer; { Item limit count }
-         Delta: Sw_Integer; { Inc delta size }
-      Constructor Init (ALimit, ADelta: Sw_Integer);
-      Constructor Load (Var S: TStream);
-      Destructor Done; Virtual;
-      Function At (Index: Sw_Integer): Pointer;
-      Function IndexOf (Item: Pointer): Sw_Integer; Virtual;
-      Function GetItem (Var S: TStream): Pointer; Virtual;
-      Function LastThat (Test: Pointer): Pointer;
-      Function FirstThat (Test: Pointer): Pointer;
-      Procedure Pack;
-      Procedure FreeAll;
-      Procedure DeleteAll;
-      Procedure Free (Item: Pointer);
-      Procedure Insert (Item: Pointer); Virtual;
-      Procedure Delete (Item: Pointer);
-      Procedure AtFree (Index: Sw_Integer);
-      Procedure FreeItem (Item: Pointer); Virtual;
-      Procedure AtDelete (Index: Sw_Integer);
-      Procedure ForEach (Action: Pointer);
-      Procedure SetLimit (ALimit: Sw_Integer); Virtual;
-      Procedure Error (Code, Info: Integer); Virtual;
-      Procedure AtPut (Index: Sw_Integer; Item: Pointer);
-      Procedure AtInsert (Index: Sw_Integer; Item: Pointer);
-      Procedure Store (Var S: TStream);
-      Procedure PutItem (Var S: TStream; Item: Pointer); Virtual;
-   END;
-   PCollection = ^TCollection;
-\end{verbatim}
-
-
-\begin{procedure}{TCollection.Init}
-\Declaration
-Constructor TCollection.Init (ALimit, ADelta: Sw\_Integer);
-\Description
-\var{Init} initializes a new instance of a collection. It sets the (initial) maximum number
-of items in the collection to \var{ALimit}. \var{ADelta} is the increase
-size : The number of memory places that will be allocatiod in case \var{ALimit} is reached, 
-and another element is added to the collection.
-\Errors
-None. 
-\SeeAlso
-\seepl{Load}{TCollection.Load}, \seepl{Done}{TCollection.Done}
-\end{procedure}
-
-For an example, see \seep{TCollection.ForEach}.
-
-\begin{procedure}{TCollection.Load}
-\Declaration
-Constructor TCollection.Load (Var S: TStream);
-\Description
-\var{Load} initializes a new instance of a collection. It reads from stream
-\var{S} the item count, the item limit count, and the increase size. After
-that, it reads the specified number of items from the stream. 
-
-% Do not call this method if you intend to use only pointers in your collection.
-\Errors
-Errors returned can be those of \seefl{GetItem}{TCollection.GetItem}.
-\SeeAlso
-\seepl{Init}{TCollection.Init}, \seefl{GetItem}{TCollection.GetItem},
-\seepl{Done}{TCollection.Done}.
-\end{procedure}
-
-\FPCexample{ex22}
-
-
-\begin{procedure}{TCollection.Done}
-\Declaration
-Destructor TCollection.Done; Virtual;
-\Description
-\var{Done} frees all objects in the collection, and then releases all memory
-occupied by the instance.
-
-% Do not call this method if you intend to use only pointers in your collection.
-\Errors
-None.
-\SeeAlso
-\seepl{Init}{TCollection.Init}, \seepl{FreeAll}{TCollection.FreeAll}
-\end{procedure}
-
-For an example, see \seep{TCollection.ForEach}.
-
-\begin{function}{TCollection.At}
-\Declaration
-Function TCollection.At (Index: Sw\_Integer): Pointer;
-\Description
-\var{At} returns the item at position \var{Index}.
-\Errors
-If \var{Index} is less than zero or larger than the number of items
-in the collection, seepl{Error}{TCollection.Error} is called with
-\var{coIndexError} and \var{Index} as arguments, resulting in a run-time
-error.
-\SeeAlso
-\seepl{Insert}{TCollection.Insert}
-\end{function}
-
-\FPCexample{ex23}
-
-
-\begin{function}{TCollection.IndexOf}
-\Declaration
-Function TCollection.IndexOf (Item: Pointer): Sw\_Integer; Virtual;
-\Description
-\var{IndexOf} returns the index of \var{Item} in the collection. 
-If \var{Item} isn't present in the collection, -1 is returned.
-\Errors
-\SeeAlso
-\end{function}
-
-\FPCexample{ex24}
-
-
-\begin{function}{TCollection.GetItem}
-\Declaration
-Function TCollection.GetItem (Var S: TStream): Pointer; Virtual;
-\Description
-\var{GetItem} reads a single item off the stream \var{S}, and
-returns a pointer to this item. This method is used internally by the Load
-method, and should not be used directly.
-\Errors
-Possible errors are the ones from \seef{TStream.Get}.
-\SeeAlso
-\seef{TStream.Get}, seepl{Store}{TCollection.Store}
-\end{function}
-
-\begin{function}{TCollection.LastThat}
-\Declaration
-Function TCollection.LastThat (Test: Pointer): Pointer;
-\Description
-This function returns the last item in the collection for which \var{Test}
-returns a non-nil result. \var{Test} is a function that accepts 1 argument:
-a pointer to an object, and that returns a pointer as a result.
-\Errors
-None.
-\SeeAlso
-\seefl{FirstThat}{TCollection.FirstThat}
-\end{function}
-
-\FPCexample{ex25}
-
-
-\begin{function}{TCollection.FirstThat}
-\Declaration
-Function TCollection.FirstThat (Test: Pointer): Pointer;
-\Description
-This function returns the first item in the collection for which \var{Test}
-returns a non-nil result. \var{Test} is a function that accepts 1 argument:
-a pointer to an object, and that returns a pointer as a result.
-\Errors
-None.
-\SeeAlso
-\seefl{LastThat}{TCollection.LastThat}
-\end{function}
-
-\FPCexample{ex26}
-
-
-\begin{procedure}{TCollection.Pack}
-\Declaration
-Procedure TCollection.Pack;
-\Description
-\var{Pack} removes all \var{Nil} pointers from the collection, and adjusts
-\var{Count} to reflect this change. No memory is freed as a result of this
-call. In order to free any memory, you can call \var{SetLimit} with an
-argument of \var{Count} after a call to \var{Pack}.
-\Errors
-None.
-\SeeAlso
-\seepl{SetLimit}{TCollection.SetLimit}
-\end{procedure}
-
-\FPCexample{ex26}
-
-
-\begin{procedure}{TCollection.FreeAll}
-\Declaration
-Procedure TCollection.FreeAll;
-\Description
-\var{FreeAll} calls the destructor of each object in the collection.
-It doesn't release any memory occumpied by the collection itself, but it
-does set \var{Count} to zero.
-\Errors
-\SeeAlso
-\seepl{DeleteAll}{TCollection.DeleteAll}, \seepl{FreeItem}{TCollection.FreeItem}
-\end{procedure}
-
-\FPCexample{ex28}
-
-
-\begin{procedure}{TCollection.DeleteAll}
-\Declaration
-Procedure TCollection.DeleteAll;
-\Description
-\var{DeleteAll} deletes all elements from the collection. It just sets 
-the \var{Count} variable to zero. Contrary to
-\seepl{FreeAll}{TCollection.FreeAll}, \var{DeletAll} doesn't call the
-destructor of the objects.
-\Errors
-None.
-\SeeAlso
-\seepl{FreeAll}{TCollection.FreeAll}, \seepl{Delete}{TCollection.Delete}
-\end{procedure}
-
-\FPCexample{ex29}
-
-
-\begin{procedure}{TCollection.Free}
-\Declaration
-Procedure TCollection.Free (Item: Pointer);
-\Description
-\var{Free} Deletes \var{Item} from the collection, and calls the destructor
-\var{Done} of the object.
-\Errors
-If the \var{Item} is not in the collection, \var{Error} will be called with
-\var{coIndexError}.
-\SeeAlso
-\seepl{FreeItem}{TCollection.FreeItem},
-\end{procedure}
-
-\FPCexample{ex30}
-
-
-\begin{procedure}{TCollection.Insert}
-\Declaration
-Procedure TCollection.Insert (Item: Pointer); Virtual;
-\Description
-\var{Insert} inserts \var{Item} in the collection. \var{TCollection}
-inserts this item at the end, but descendent objects may insert it at
-another place.
-\Errors
-None.
-\SeeAlso
-\seepl{AtInsert}{TCollection.AtInsert}, \seepl{AtPut}{TCollection.AtPut},
-\end{procedure}
-
-
-\begin{procedure}{TCollection.Delete}
-\Declaration
-Procedure TCollection.Delete (Item: Pointer);
-\Description
-\var{Delete} deletes \var{Item} from the collection. It doesn't call the
-item's destructor, though. For this the \seepl{Free}{TCollection.Free}
-call is provided.
-\Errors
-If the \var{Item} is not in the collection, \var{Error} will be called with
-\var{coIndexError}.
-\SeeAlso
-\seepl{AtDelete}{TCollection.AtDelete},\seepl{Free}{TCollection.Free}
-\end{procedure}
-
-\FPCexample{ex31}
-
-
-\begin{procedure}{TCollection.AtFree}
-\Declaration
-Procedure TCollection.AtFree (Index: Sw\_Integer);
-\Description
-\var{AtFree} deletes the item at position \var{Index} in the collection,
-and calls the item's destructor if it is not \var{Nil}. 
-\Errors
-If \var{Index} isn't valid then \seepl{Error}{TCollection.Error} is called
-with \var{CoIndexError}.
-\SeeAlso
-\seepl{Free}{TCollection.Free}, \seepl{AtDelete}{TCollection.AtDelete}
-\end{procedure}
-
-\FPCexample{ex32}
-
-
-\begin{procedure}{TCollection.FreeItem}
-\Declaration
-Procedure TCollection.FreeItem (Item: Pointer); Virtual;
-\Description
-\var{FreeItem} calls the destructor of \var{Item} if it is not nil.
-
-This function is used internally by the TCollection object, and should not be
-called directly.
-\Errors
-None.
-\SeeAlso
-\seepl{Free}{TCollection.AtFree}, seepl{AtFree}{TCollection.AtFree}
-\end{procedure}
-
-
-\begin{procedure}{TCollection.AtDelete}
-\Declaration
-Procedure TCollection.AtDelete (Index: Sw\_Integer);
-\Description
-\var{AtDelete} deletes the pointer at position \var{Index} in the
-collection. It doesn't call the object's destructor.
-\Errors
-If \var{Index} isn't valid then \seepl{Error}{TCollection.Error} is called
-with \var{CoIndexError}.
-\SeeAlso
-\seepl{Delete}{TCollection.Delete}
-\end{procedure}
-
-
-\FPCexample{ex33}
-
-
-\begin{procedure}{TCollection.ForEach}
-\Declaration
-Procedure TCollection.ForEach (Action: Pointer);
-\Description
-\var{ForEach} calls \var{Action} for each element in the collection,
-and passes the element as an argument to \var{Action}.
-
-\var{Action} is a procedural type variable that accepts a pointer as an 
-argument.
-\Errors
-None.
-\SeeAlso
-\seefl{FirstThat}{TCollection.FirstThat}, \seefl{LastThat}{TCollection.LastThat}
-\end{procedure}
-
-\FPCexample{ex21}
-
-
-\begin{procedure}{TCollection.SetLimit}
-\Declaration
-Procedure TCollection.SetLimit (ALimit: Sw\_Integer); Virtual;
-\Description
-\var{SetLimit} sets the maximum number of elements in the collection.
-\var{ALimit} must not be less than \var{Count}, and should not be larger
-than \var{MaxCollectionSize}
-\Errors
-None.
-\SeeAlso
-\seepl{Init}{TCollection.Init}
-\end{procedure}
-
-For an example, see \seepl{Pack}{TCollection.Pack}.
-
-\begin{procedure}{TCollection.Error}
-\Declaration
-Procedure TCollection.Error (Code, Info: Integer); Virtual;
-\Description
-\var{Error} is called by the various \var{TCollection} methods
-in case of an error condition. The default behaviour is to make
-a call to \var{RunError} with an error of \var{212-Code}.
-
-This method can be overridden by descendent objects to implement
-a different error-handling.
-\Errors
-\SeeAlso
-\seep{Abstract}
-\end{procedure}
-
-\begin{procedure}{TCollection.AtPut}
-\Declaration
-Procedure TCollection.AtPut (Index: Sw\_Integer; Item: Pointer);
-\Description
-\var{AtPut} sets the element at position \var{Index} in the collection
-to \var{Item}. Any previous value is overwritten.
-\Errors
-If \var{Index} isn't valid then \seepl{Error}{TCollection.Error} is called
-with \var{CoIndexError}.
-\SeeAlso
-\end{procedure}
-
-For an example, see \seepl{Pack}{TCollection.Pack}.
-
-\begin{procedure}{TCollection.AtInsert}
-\Declaration
-Procedure TCollection.AtInsert (Index: Sw\_Integer; Item: Pointer);
-\Description
-\var{AtInsert} inserts \var{Item} in the collection at position \var{Index},
-shifting all elements by one position. In case the current limit is reached,
-the collection will try to expand with a call to \var{SetLimit}
-\Errors
-If \var{Index} isn't valid then \seepl{Error}{TCollection.Error} is called
-with \var{CoIndexError}. If the collection fails to expand, then
-\var{coOverFlow} is passd to \var{Error}.
-\SeeAlso
-\seepl{Insert}{TCollection.Insert}
-\end{procedure}
-
-\FPCexample{ex34}
-
-
-\begin{procedure}{TCollection.Store}
-\Declaration
-Procedure TCollection.Store (Var S: TStream);
-\Description
-\var{Store} writes the collection to the stream \var{S}. It does
-this by writeing the current \var{Count}, \var{Limit} and \var{Delta}
-to the stream, and then writing each item to the stream.
-
-The contents of the stream are then suitable for instantiating another
-collection with \seepl{Load}{TCollection.Load}.
-\Errors
-Errors returned are those by \seep{TStream.Put}.
-\SeeAlso
-\seepl{Load}{TCollection.Load}, \seepl{PutItem}{TCollection.PutItem}
-\end{procedure}
-
-For an example, see seepl{Load}{TCollection.Load}.
-
-\begin{procedure}{TCollection.PutItem}
-\Declaration
-Procedure TCollection.PutItem (Var S: TStream; Item: Pointer); Virtual;
-\Description
-\var{PutItem} writes \var{Item} to stream \var{S}. This method is used
-internaly by the \var{TCollection} object, and should not be called
-directly.
-\Errors
-Errors are those returned by \seep{TStream.Put}.
-\SeeAlso
-\seepl{Store}{TCollection.Store}, \seefl{GetItem}{TCollection.GetItem}.
-\end{procedure}
-
-\section{TSortedCollection}
-\label{se:TSortedCollection}
-
-\var{TSortedCollection} is an abstract class, implementing a sorted
-collection. You should never use an instance of \var{TSortedCollection}
-directly, instead you should declare a descendent type, and override the
-\seefl{Compare}{TSortedCollection.Compare} method.
-
-Because the collection is ordered, \var{TSortedCollection} overrides some
-\var{TCollection} methods, to provide faster routines for lookup.
-
-The \seefl{Compare}{TSortedCollection.Compare} method decides how elements 
-in the collection should be ordered. Since \var{TCollection} has no way
-of knowing how to order pointers, you must override the compare method.
-
-Additionally, \var{TCollection} provides a means to filter out duplicates.
-if you set \var{Duplicates} to \var{False} (the default) then duplicates
-will not be allowed.
-
-Here is the complete declaration of \var{TSortedCollection}
-
-\begin{verbatim}
-TYPE
-   TSortedCollection = OBJECT (TCollection)
-         Duplicates: Boolean; { Duplicates flag }
-      Constructor Init (ALimit, ADelta: Sw_Integer);
-      Constructor Load (Var S: TStream);
-      Function KeyOf (Item: Pointer): Pointer; Virtual;
-      Function IndexOf (Item: Pointer): Sw_Integer; Virtual;
-      Function Compare (Key1, Key2: Pointer): Sw_Integer; Virtual;
-      Function Search (Key: Pointer; Var Index: Sw_Integer): Boolean;Virtual;
-      Procedure Insert (Item: Pointer); Virtual;
-      Procedure Store (Var S: TStream);
-   END;
-   PSortedCollection = ^TSortedCollection;
-\end{verbatim}
-
-In the subsequent examples, the following descendent of
-\var{TSortedCollection} is used:
-
-\FPCexample{mysortc}
-
-
-\begin{procedure}{TSortedCollection.Init}
-\Declaration
-Constructor TSortedCollection.Init (ALimit, ADelta: Sw\_Integer);
-\Description
-\var{Init} calls the inherited constuctor (see \seep{TCollection.Init}) and
-sets the \var{Duplicates} flag to false.
-
-You should not call this method directly, since \var{TSortedCollection} is a
-abstract class. Instead, the descendent classes should call it via the
-\var{inherited} keyword.
-\Errors
-None.
-\SeeAlso 
-\seepl{Load}{TSortedCollection.Load}, \seepl{Done}{TCollection.Done}
-\end{procedure}
-
-For an example, see 
-
-\begin{procedure}{TSortedCollection.Load}
-\Declaration
-Constructor Load (Var S: TStream);
-\Description
-\var{Load} calls the inherited constuctor (see \seep{TCollection.Load}) and
-reads the \var{Duplicates} flag from the stream..
-
-You should not call this method directly, since \var{TSortedCollection} is a
-abstract class. Instead, the descendent classes should call it via the
-\var{inherited} keyword.
-\Errors
-None.
-\SeeAlso 
-\seepl{Init}{TSortedCollection.Init}, \seepl{Done}{TCollection.Done}
-\end{procedure}
-
-For an example, see \seep{TCollection.Load}.
-
-\begin{function}{TSortedCollection.KeyOf}
-\Declaration
-Function TSortedCollection.KeyOf (Item: Pointer): Pointer; Virtual;
-\Description
-\var{KeyOf} returns the key associated with \var{Item}.
-\var{TSortedCollection} returns the item itself as the key, descendent
-objects can override this method to calculate a (unique) key based on the
-item passed (such as hash values).
-
-\var{Keys} are used to sort the objects, they are used to search and sort
-the items in the collection. If descendent types override this method then
-it allows possibly for faster search/sort methods based on keys rather than
-on the objects themselves.
-\Errors
-None.
-\SeeAlso
-\seefl{IndexOf}{TSortedCollection.IndexOf},
-\seefl{Compare}{TSortedCollection.Compare}.
-\end{function}
-
-\begin{function}{TSortedCollection.IndexOf}
-\Declaration
-Function TSortedCollection.IndexOf (Item: Pointer): Sw\_Integer; Virtual;
-\Description
-\var{IndexOf} returns the index of \var{Item} in the collection. It searches
-for the object based on it's key. If duplicates are allowed, then it returns 
-the index of last object that matches \var{Item}.
-
-In case \var{Item} is not found in the collection, -1 is returned.
-\Errors
-None.
-\SeeAlso
-\seefl{Search}{TSortedCollection.Search},
-\seefl{Compare}{TSortedCollection.Compare}.
-\end{function}
-
-For an example, see \seef{TCollection.IndexOf}
-
-\begin{function}{TSortedCollection.Compare}
-\Declaration
-Function TSortedCollection.Compare (Key1, Key2: Pointer): Sw\_Integer; Virtual;
-\Description
-\var{Compare} is an abstract method that should be overridden by descendent
-objects in order to compare two items in the collection. This method is used
-in the \seefl{Search}{TSortedCollection.Search} method and in the
-\seepl{Insert}{TSortedCollection.Insert} method to determine the ordering of
-the objects.
-
-The function should compare the two keys of items and return the following
-function results:
-\begin{description}
-\item [Result < 0] If \var{Key1} is logically before \var{Key2}
-(\var{Key1<Key2})
-\item [Result = 0] If \var{Key1} and \var{Key2} are equal. (\var{Key1=Key2})
-\item [Result > 0] If \var{Key1} is logically after \var{Key2}
-(\var{Key1>Key2})
-\end{description}
-\Errors
-An 'abstract run-time error' will be generated if you call
-\var{TSortedCollection.Compare} directly.
-\SeeAlso
-\seefl{IndexOf}{TSortedCollection.IndexOf},
-\seefl{Search}{TSortedCollection.Search}
-\end{function}
-
-\FPCexample{mysortc}
-
-
-\begin{function}{TSortedCollection.Search}
-\Declaration
-Function TSortedCollection.Search (Key: Pointer; Var Index: Sw\_Integer): Boolean;Virtual;
-\Description
-\var{Search} looks for the item with key \var{Key} and returns the position 
-of the item (if present) in the collection in \var{Index}.
-
-Instead of a linear search as \var{TCollection} does, \var{TSortedCollection}
-uses a binary search based on the keys of the objects. It uses the
-\seefl{Compare}{TSortedCollection.Compare} function to implement this
-search. 
-
-If the item is found, \var{Search} returns \var{True}, otherwise \var{False}
-is returned.
-\Errors
-None.
-\SeeAlso
-\seefl{IndexOf}{TCollection.IndexOf}.
-\end{function}
-
-\FPCexample{ex36}
-
-
-\begin{procedure}{TSortedCollection.Insert}
-\Declaration
-Procedure TSortedCollection.Insert (Item: Pointer); Virtual;
-\Description
-\var{Insert} inserts an item in the collection at the correct position, such
-that the collection is ordered at all times. You should never use
-\seepl{Atinsert}{TCollection.AtInsert}, since then the collection ordering
-is not guaranteed.
-
-If \var{Item} is already present in the collection, and \var{Duplicates} is
-\var{False}, the item will not be inserted.
-\Errors
-None.
-\SeeAlso
-\seepl{AtInsert}{TCollection.AtInsert}
-\end{procedure}
-
-\FPCexample{ex35}
-
-
-\begin{procedure}{TSortedCollection.Store}
-\Declaration
-Procedure TSortedCollection.Store (Var S: TStream);
-\Description
-\var{Store} writes the collection to the stream \var{S}. It does this by
-calling the inherited \seep{TCollection.Store}, and then writing the
-\var{Duplicates} flag to the stream.
-
-After a \var{Store}, the collection can be loaded from the stream with the 
-constructor \seepl{Load}{TSortedCollection.Load}
-\Errors
-Errors can be those of \seep{TStream.Put}.
-\SeeAlso
-\seepl{Load}{TSortedCollection.Load}
-\end{procedure}
-
-For an example, see \seep{TCollection.Load}.
-
-\section{TStringCollection}
-\label{se:TStringCollection}
-
-The \var{TStringCollection} object manages a sorted collection of pascal 
-strings. 
-To this end, it overrides the \seefl{Compare}{TSortedCollection.Compare}
-method of \var{TSortedCollection}, and it introduces methods to read/write
-strings from a stream.
-
-Here is the full declaration of the \var{TStringCollection} object:
-\begin{verbatim}
-TYPE
-   TStringCollection = OBJECT (TSortedCollection)
-      Function GetItem (Var S: TStream): Pointer; Virtual;
-      Function Compare (Key1, Key2: Pointer): Sw_Integer; Virtual;
-      Procedure FreeItem (Item: Pointer); Virtual;
-      Procedure PutItem (Var S: TStream; Item: Pointer); Virtual;
-   END;
-   PStringCollection = ^TStringCollection;
-\end{verbatim}
-
-\begin{function}{TStringCollection.GetItem}
-\Declaration
-Function TStringCollection.GetItem (Var S: TStream): Pointer; Virtual;
-\Description
-\var{GetItem} reads a string from the stream \var{S} and returns a pointer 
-to it. It doesn't insert the string in the collection.
-
-This method is primarily introduced to be able to load and store the
-collection from and to a stream.
-\Errors
-The errors returned are those of \seef{TStream.ReadStr}.
-\SeeAlso
-\seepl{PutItem}{TStringCollection.PutItem}
-\end{function}
-
-\begin{function}{TStringCollection.Compare}
-\Declaration
-Function TStringCollection.Compare (Key1, Key2: Pointer): Sw\_Integer; Virtual;
-\Description
-\var{TStringCollection} overrides the \var{Compare} function so it compares 
-the two keys as if they were pointers to strings. The compare is done case
-sensitive. It returns the following results:
-\begin{description}
-\item[-1] if the first string is alphabetically earlier  than the second
-string.
-\item[0] if the two strings are equal.
-\item[1] if the first string is alphabetically later than the second string.
-\end{description}
-\Errors
-None.
-\SeeAlso
-\seef{TSortedCollection.Compare}
-\end{function}
-
-\FPCexample{ex37}
-
-
-\begin{procedure}{TStringCollection.FreeItem}
-\Declaration
-Procedure TStringCollection.FreeItem (Item: Pointer); Virtual;
-\Description
-\var{TStringCollection} overrides \var{FreeItem} so that the string pointed
-to by \var{Item} is disposed from memory.
-\Errors
-None.
-\SeeAlso
-\seep{TCollection.FreeItem}
-\end{procedure}
-
-\begin{procedure}{TStringCollection.PutItem}
-\Declaration
-Procedure TStringCollection.PutItem (Var S: TStream; Item: Pointer); Virtual;
-\Description
-\var{PutItem} writes the string pointed to by \var{Item} to the stream
-\var{S}. 
-
-This method is primarily used in the \var{Load} and \var{Store} methods, 
-and should not be used directly.
-\Errors
-Errors are those of \seep{TStream.WriteStr}.
-\SeeAlso
-\seefl{GetItem}{TStringCollection.GetItem}
-\end{procedure}
-
-
-\section{TStrCollection}
-\label{se:TStrCollection}
-
-The \var{TStrCollection} object manages a sorted collection
-of null-terminated strings (pchar strings).  
-To this end, it overrides the \seefl{Compare}{TSortedCollection.Compare}
-method of \var{TSortedCollection}, and it introduces methods to read/write
-strings from a stream.
-
-Here is the full declaration of the \var{TStrCollection} object:
-
-\begin{verbatim}
-TYPE
-   TStrCollection = OBJECT (TSortedCollection)
-      Function Compare (Key1, Key2: Pointer): Sw_Integer; Virtual;
-      Function GetItem (Var S: TStream): Pointer; Virtual;
-      Procedure FreeItem (Item: Pointer); Virtual;
-      Procedure PutItem (Var S: TStream; Item: Pointer); Virtual;
-   END;
-   PStrCollection = ^TStrCollection;
-\end{verbatim}
-
-\begin{function}{TStrCollection.GetItem}
-\Declaration
-Function TStrCollection.GetItem (Var S: TStream): Pointer; Virtual;
-\Description
-\var{GetItem} reads a null-terminated string from the stream \var{S} 
-and returns a pointer  to it. It doesn't insert the string in the 
-collection.
-
-This method is primarily introduced to be able to load and store the
-collection from and to a stream.
-\Errors
-The errors returned are those of \seef{TStream.StrRead}.
-\SeeAlso
-\seepl{PutItem}{TStrCollection.PutItem}
-\end{function}
-
-\begin{function}{TStrCollection.Compare}
-\Declaration
-Function TStrCollection.Compare (Key1, Key2: Pointer): Sw\_Integer; Virtual;
-\Description
-\var{TStrCollection} overrides the \var{Compare} function so it compares 
-the two keys as if they were pointers to strings. The compare is done case
-sensitive. It returns
-\begin{description}
-\item[-1] if the first string is alphabetically earlier  than the second
-string.
-\item[0] if the two strings are equal.
-\item[1] if the first string is alphabetically later than the second string.
-\end{description}
-\Errors
-None.
-\SeeAlso
-\seef{TSortedCollection.Compare}
-\end{function}
-
-\FPCexample{ex38}
-
-
-\begin{procedure}{TStrCollection.FreeItem}
-\Declaration
-Procedure TStrCollection.FreeItem (Item: Pointer); Virtual;
-\Description
-\var{TStrCollection} overrides \var{FreeItem} so that the string pointed
-to by \var{Item} is disposed from memory.
-\Errors
-None.
-\SeeAlso
-\seep{TCollection.FreeItem}
-\end{procedure}
-
-\begin{procedure}{TStrCollection.PutItem}
-\Declaration
-Procedure TStrCollection.PutItem (Var S: TStream; Item: Pointer); Virtual;
-\Description
-\var{PutItem} writes the string pointed to by \var{Item} to the stream
-\var{S}. 
-
-This method is primarily used in the \var{Load} and \var{Store} methods, 
-and should not be used directly.
-\Errors
-Errors are those of \seep{TStream.StrWrite}.
-\SeeAlso
-\seefl{GetItem}{TStrCollection.GetItem}
-\end{procedure}
-
-\section{TUnSortedStrCollection}
-\label{se:TUnSortedStrCollection}
-
-The \var{TUnSortedStrCollection} object manages an unsorted list of strings.
-To this end, it overrides the \seep{TStringCollection.Insert} method to add
-strings at the end of the collection, rather than in the alphabetically
-correct position.
-
-Take care, the \seefl{Search}{TSortedCollection.Search} and
-\seefl{IndexOf}{TCollection.IndexOf} methods will not work on an unsorted
-string collection.
-
-Here is the full declaration of the {TUnsortedStrCollection} object:
-\begin{verbatim}
-TYPE
-   TUnSortedStrCollection = OBJECT (TStringCollection)
-      Procedure Insert (Item: Pointer); Virtual;
-   END;
-   PUnSortedStrCollection = ^TUnSortedStrCollection;
-\end{verbatim}
-
-\begin{procedure}{TUnSortedStrCollection.Insert}
-\Declaration
-Procedure TUnSortedStrCollection.Insert (Item: Pointer); Virtual;
-\Description
-\var{Insert} inserts a string at the end of the collection, instead
-of on it's alphabetical place, resulting in an unsorted collection of
-strings. 
-\Errors
-\SeeAlso
-\end{procedure}
-
-\FPCexample{ex39}
-
-
-\section{TResourceCollection}
-\label{se:TResourceCollection}
-
-A \var{TResourceCollection} manages a collection of resource names. 
-It stores the position and the size of a resource, as well as the name of
-the resource. It stores these items in records that look like this:
-\begin{verbatim}
-TYPE
-   TResourceItem = packed RECORD
-      Posn: LongInt;
-      Size: LongInt;
-      Key : String;
-   End;
-   PResourceItem = ^TResourceItem;
-\end{verbatim}
-
-It overrides some methods of \var{TStringCollection} in order to accomplish
-this. 
-
-Remark that the \var{TResourceCollection} manages the names of the
-resources and their assiciated positions and sizes, it doesn't manage
-the resources themselves.
-
-Here is the full declaration of the \var{TResourceCollection} object:
-\begin{verbatim}
-TYPE
-   TResourceCollection = OBJECT (TStringCollection)
-      Function KeyOf (Item: Pointer): Pointer; Virtual;
-      Function GetItem (Var S: TStream): Pointer; Virtual;
-      Procedure FreeItem (Item: Pointer); Virtual;
-      Procedure PutItem (Var S: TStream; Item: Pointer); Virtual;
-   END;
-   PResourceCollection = ^TResourceCollection;
-\end{verbatim}
-
-\begin{function}{TResourceCollection.KeyOf}
-\Declaration
-Function TResourceCollection.KeyOf (Item: Pointer): Pointer; Virtual;
-\Description
-\var{KeyOf} returns the key of an item in the collection. For resources, the
-key is a pointer to the string with the resource name.
-\Errors
-None.
-\SeeAlso
-\seef{TStringCollection.Compare}
-\end{function}
-
-\begin{function}{TResourceCollection.GetItem}
-\Declaration
-Function TResourceCollection.GetItem (Var S: TStream): Pointer; Virtual;
-\Description
-\var{GetItem} reads a resource item from the stream \var{S}. It reads the
-position, size and name from the stream, in that order. It DOES NOT read the
-resource itself from the stream.
-
-The resulting item is not inserted in the collection. This call is manly for
-internal use by the \seep{TCollection.Load} method.
-\Errors
-Errors returned are those by \seep{TStream.Read}
-\SeeAlso
-\seep{TCollection.Load}, \seep{TStream.Read}
-\end{function}
-
-\begin{procedure}{TResourceCollection.FreeItem}
-\Declaration
-Procedure TResourceCollection.FreeItem (Item: Pointer); Virtual;
-\Description
-\var{FreeItem} releases the memory occupied by \var{Item}. It de-allocates
-the name, and then the resourceitem record.
-
-It does NOT remove the item from the collection.
-\Errors
-None.
-\SeeAlso
-\seep{TCollection.FreeItem}
-\end{procedure}
-
-\begin{procedure}{TResourceCollection.PutItem}
-\Declaration
-Procedure TResourceCollection.PutItem (Var S: TStream; Item: Pointer); Virtual;
-\Description
-\var{PutItem} writes \var{Item} to the stream \var{S}. It does this by
-writing the position and size and name of the resource item to the stream.
-
-This method is used primarily by the \seepl{Store}{TCollection.Store}
-method.
-\Errors
-Errors returned are those by \seep{TStream.Write}.
-\SeeAlso
-\seepl{Store}{TCollection.Store}
-\end{procedure}
-
-
-\section{TResourceFile}
-\label{se:TResourceFile}
-
-\begin{verbatim}
-TYPE
-   TResourceFile = OBJECT (TObject)
-         Stream  : PStream; { File as a stream }
-         Modified: Boolean; { Modified flag }
-      Constructor Init (AStream: PStream);
-      Destructor Done; Virtual;
-      Function Count: Sw_Integer;
-      Function KeyAt (I: Sw_Integer): String;
-      Function Get (Key: String): PObject;
-      Function SwitchTo (AStream: PStream; Pack: Boolean): PStream;
-      Procedure Flush;
-      Procedure Delete (Key: String);
-      Procedure Put (Item: PObject; Key: String);
-   END;
-   PResourceFile = ^TResourceFile;
-\end{verbatim}
-
-\subsection{TResourceFile Fields}
-
-\var{TResourceFile} has the following fields:
-\begin{description}
-\item[Stream] contains the (file) stream that has the executable image and
-the resources. It can be initialized by the \seepl{Init}{TResourceFile.Init}
-constructor call.
-\item[Modified] is set to \var{True} if one of the resources has been changed.
-It is set by the \seepl{SwitchTo}{TResourceFile.Init},
-\seepl{Delete}{TResourceFile.Delete} and \seepl{Put}{TResourceFile.Put}
-methods. Calling \seepl{Flush}{TResourceFile.Flush} will clear the
-\var{Modified} flag.
-\end{description}
-
-\begin{procedure}{TResourceFile.Init}
-\Declaration
-Constructor TResourceFile.Init (AStream: PStream);
-\Description
-\var{Init} instantiates a new instance of a \var{TResourceFile} object.
-If \var{AStream} is not nil then it is considered as a stream describing an
-executable image on disk. 
-
-\var{Init} will try to position the stream on the start of the resources section,
-and read all resources from the stream.
-\Errors
-None.
-\SeeAlso
-\seepl{Done}{TResourceFile.Done}
-\end{procedure}
-
-\begin{procedure}{TResourceFile.Done}
-\Declaration
-Destructor TResourceFile.Done; Virtual;
-\Description
-\var{Done} cleans up the instance of the \var{TResourceFile} Object. 
-If \var{Stream} was specified at initialization, then \var{Stream} is 
-disposed of too.
-\Errors
-None.
-\SeeAlso
-\seepl{Init}{TResourceFile.Init}
-\end{procedure}
-
-\begin{function}{TResourceFile.Count}
-\Declaration
-Function TResourceFile.Count: Sw\_Integer;
-\Description
-\var{Count} returns the number of resources. If no resources were
-read, zero is returned.
-\Errors
-None.
-\SeeAlso
-\seepl{Init}{TResourceFile.Init}
-\end{function}
-
-\begin{function}{TResourceFile.KeyAt}
-\Declaration
-Function TResourceFile.KeyAt (I: Sw\_Integer): String;
-\Description
-\var{KeyAt} returns the key (the name) of the \var{I}-th resource.
-\Errors
-In case \var{I} is invalid, \var{TCollection.Error} will be executed.
-\SeeAlso
-\seefl{Get}{TResourceFile.Get}
-\end{function}
-
-\begin{function}{TResourceFile.Get}
-\Declaration
-Function TResourceFile.Get (Key: String): PObject;
-\Description
-\var{Get} returns a pointer to a instance of a resource identified by
-\var{Key}. If \var{Key} cannot be found in the list of resources, then
-\var{Nil} is returned.
-\Errors
-Errors returned may be those by \var{TStream.Get}
-\SeeAlso
-\end{function}
-
-\begin{function}{TResourceFile.SwitchTo}
-\Declaration
-Function TResourceFile.SwitchTo (AStream: PStream; Pack: Boolean): PStream;
-\Description
-\var{SwitchTo} switches to a new stream to hold the resources in.
-\var{AStream} will be the new stream after the call to \var{SwitchTo}.
-
-If \var{Pack} is true, then all the known resources will be copied from 
-the current stream to the new stream (\var{AStream}). If \var{Pack} is 
-\var{False}, then only the current resource is copied.
-
-The return value is the value of the original stream: \var{Stream}.
-
-The \var{Modified} flag is set as a consequence of this call.
-\Errors
-Errors returned can be those of \seep{TStream.Read} and
-\seep{TStream.Write}.
-\SeeAlso
-\seepl{Flush}{TResourceFile.Flush}
-\end{function}
-
-\begin{procedure}{TResourceFile.Flush}
-\Declaration
-Procedure TResourceFile.Flush;
-\Description
-If the \var{Modified} flag is set to \var{True}, then \var{Flush} 
-writes the resources to the stream \var{Stream}. It sets the \var{Modified}
-flag to true after that.
-\Errors
-Errors can be those by \seep{TStream.Seek} and \seep{TStream.Write}.
-\SeeAlso
-\seefl{SwitchTo}{TResourceFile.SwitchTo}
-\end{procedure}
-
-\begin{procedure}{TResourceFile.Delete}
-\Declaration
-Procedure TResourceFile.Delete (Key: String);
-\Description
-\var{Delete} deletes the resource identified by \var{Key} from the
-collection. It sets the \var{Modified} flag to true.
-\Errors
-None.
-\SeeAlso
-\seepl{Flush}{TResourceFile.Flush}
-\end{procedure}
-
-\begin{procedure}{TResourceFile.Put}
-\Declaration
-Procedure TResourceFile.Put (Item: PObject; Key: String);
-\Description
-\var{Put} sets the resource identified by \var{Key} to \var{Item}.
-If no such resource exists, a new one is created. The item is written
-to the stream.
-\Errors
-Errors returned may be those by \seep{TStream.Put} and \var{TStream.Seek}
-\SeeAlso
-\seefl{Get}{TResourceFile.Get}
-\end{procedure}
-
-\section{TStringList}
-\label{se:TStringList}
-
-A \var{TStringList} object can be used to read a collection of strings
-stored in a stream. If you register this object with the \seep{RegisterType}
-function, you cannot register the \var{TStrListMaker} object.
-
-This is the public declaration of the \var{TStringList} object:
-\begin{verbatim}
-TYPE
-   TStrIndexRec = Packed RECORD
-      Key, Count, Offset: Word;
-   END;
-
-   TStrIndex = Array [0..9999] Of TStrIndexRec;
-   PStrIndex = ^TStrIndex;
-
-   TStringList = OBJECT (TObject)
-      Constructor Load (Var S: TStream);
-      Destructor Done; Virtual;
-      Function Get (Key: Sw_Word): String;
-   END;
-   PStringList = ^TStringList;
-\end{verbatim}
-
-\begin{procedure}{TStringList.Load}
-\Declaration
-Constructor TstringList.Load (Var S: TStream);
-\Description
-The \var{Load} constructor reads the \var{TStringList} object from the
-stream \var{S}. It also reads the descriptions of the strings from the
-stream. The string descriptions are stored as an array of 
-\var{TstrIndexrec} records, where each record describes a string on the
-stream. These records are kept in memory.
-\Errors
-If an error occurs, a stream error is triggered.
-\SeeAlso
-\seepl{Done}{TStringList.Done}
-\end{procedure}
-
-\begin{procedure}{TStringList.Done}
-\Declaration
-Destructor TstringList.Done; Virtual;
-\Description
-The \var{Done} destructor frees the memory occupied by the string
-descriptions, and destroys the object.
-\Errors
-None.
-\SeeAlso
-\seepl{Load}{TStringList.Load}, \seep{TObject.Done}
-\end{procedure}
-
-\begin{function}{TStringList.Get}
-\Declaration
-Function TStringList.Get (Key: Sw\_Word): String;
-\Description
-\var{Get} reads the string with key \var{Key} from the list of strings on the
-stream, and returns this string. If there is no string with such a key, an
-empty string is returned.
-\Errors
-If no string with key \var{Key} is found, an empty string is returned.
-A stream error may result if the stream doesn't contain the needed strings.
-\SeeAlso
-\seep{TStrListMaker.Put}
-\end{function}
-\section{TStrListMaker}
-\label{se:TStrListMaker}
-
-The \var{TStrListMaker} object can be used to generate a stream with
-strings, which can be read with the \var{TStringList} object.
-If you register this object with the \seep{RegisterType}
-function, you cannot register the \var{TStringList} object.
-
-This is the public declaration of the \var{TStrListMaker} object:
-\begin{verbatim}
-TYPE
-   TStrListMaker = OBJECT (TObject)
-      Constructor Init (AStrSize, AIndexSize: Sw_Word);
-      Destructor Done; Virtual;
-      Procedure Put (Key: SwWord; S: String);
-      Procedure Store (Var S: TStream);
-   END;
-   PStrListMaker = ^TStrListMaker;
-\end{verbatim}
-
-\begin{procedure}{TStrListMaker.Init}
-\Declaration
-Constructor TStrListMaker.Init (AStrSize, AIndexSize: SwWord);
-\Description
-The \var{Init} constructor creates a new instance of the \var{TstrListMaker}
-object. It allocates \var{AStrSize} bytes on the heap to hold all the
-strings you wish to store. It also allocates enough room for 
-\var{AIndexSize} key description entries (of the type \var{TStrIndexrec}).
-
-\var{AStrSize} must be large enough to contain all the strings you wish to
-store. If not enough memory is allocated, other memory will be overwritten.
-The same is true for \var{AIndexSize} : maximally \var{AIndexSize} strings
-can be written to the stream.
-\Errors
-None.
-\SeeAlso
-\seep{TObject.Init}, \seepl{Done}{TStrListMaker.Done}
-\end{procedure}
-
-\begin{procedure}{TStrListMaker.Done}
-\Declaration
-Destructor TStrListMaker.Done; Virtual;
-\Description
-The \var{Done} destructor de-allocates the memory for the index description
-records and the string data, and then destroys the object. 
-\Errors
-None.
-\SeeAlso
-\seep{TObject.Done}, \seepl{Init}{TStrListMaker.Init}
-\end{procedure}
-
-\begin{procedure}{TStrListMaker.Put}
-\Declaration
-Procedure TStrListMaker.Put (Key: Sw\_Word; S: String);
-\Description
-\var{Put} adds they string \var{S} with key \var{Key} to the collection of
-strings. This action doesn't write the string to a stream. To write the
-strings to the stream, see the \seepl{Store}{TStrListMaker.Store} method.
-\Errors
-None.
-\SeeAlso
-\seepl{Store}{TStrListMaker.Store}.
-\end{procedure}
-
-\begin{procedure}{TStrListMaker.Store}
-\Declaration
-Procedure TStrListMaker.Store (Var S: TStream);
-\Description
-\var{Store} writes the collection of strings to the stream \var{S}.
-The collection can then be read with the \var{TStringList} object.
-\Errors
-A stream error may occur when writing the strings to the stream.
-\SeeAlso
-\seep{TStringList.Load}, \seepl{Put}{TStrListMaker.Put}.
-\end{procedure}
-
-

docs/objpas.xml

@@ -0,0 +1,570 @@
+<?xml version="1.0" encoding="ISO8859-1"?>
+<fpdoc-descriptions>
+<!--  
+
+   $Id$ 
+   This file is part of the FPC documentation. 
+   Copyright (C) 1997, by Michael Van Canneyt 
+ 
+   The FPC documentation is free text; you can redistribute it and/or 
+   modify it under the terms of the GNU Library General Public License as 
+   published by the Free Software Foundation; either version 2 of the 
+   License, or (at your option) any later version. 
+ 
+   The FPC Documentation is distributed in the hope that it will be useful, 
+   but WITHOUT ANY WARRANTY; without even the implied warranty of 
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU 
+   Library General Public License for more details. 
+ 
+   You should have received a copy of the GNU Library General Public 
+   License along with the FPC documentation; see the file COPYING.LIB.  If not, 
+   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, 
+   Boston, MA 02111-1307, USA. 
+ -->
+<package name="rtl">
+<module name="objpas">
+<short>Objpas - Delphi and objfpc mode system overrides</short>
+<descr>
+<p>
+The <file>objpas</file> unit is meant for compatibility with Object Pascal as
+implemented by Delphi. The unit is loaded automatically by the Free Pascal compiler
+whenever the <var>Delphi</var> or <var>objfpc</var> more is entered, either through
+the command line switches <var>-Sd</var> or <var>-Sh</var> or with the 
+<var>{$MODE DELPHI}</var> or <var>{$MODE OBJFPC}</var> directives.
+</p>
+<p>
+It redefines some basic pascal types, introduces some functions for
+compatibility with Delphi's system unit, and introduces some methods for the
+management of the resource string tables.
+</p>
+</descr>
+
+<element name="TResourceIterator">
+<short>Enumeration callback type for resource strings</short>
+<descr>
+<p>
+The resource string tables can be managed with a callback function which the
+user must provide: <var>TResourceIterator</var>.
+</p>
+</descr>
+</element>
+
+<element name="AssignFile">
+<short>Assign text or untyped file</short>
+<descr>
+<p>
+<var>AssignFile</var> is completely equivalent to the system unit's <link
+id="#rtl.system.Assign">Assign</link>
+function: It assigns <var>Name</var> to a function of any type (<var>FileType</var>
+can be <var>Text</var> or a typed or untyped <var>File</var> variable). <var>Name</var> can
+be a string, a single character or a <var>PChar</var>.
+</p>
+<p>
+It is most likely introduced to avoid confusion between the regular
+<link id="#rtl.system.Assign">Assign</link> function and the <var>Assign</var> method of <var>TPersistent</var>
+in the Delphi VCL.
+</p>
+</descr>
+<errors>
+None.
+</errors>
+<seealso>
+<link id="CloseFile"/>
+<link id="#rtl.system.Assign"/>
+<link id="#rtl.system.Reset"/>
+<link id="#rtl.system.Rewrite"/>
+<link id="#rtl.system.Append"/>
+</seealso>
+<example file="refex/ex88"/>
+</element>
+
+<element name="CloseFile">
+<short>Close text or untyped file </short>
+<descr>
+<p>
+<var>CloseFile</var> flushes and closes a file <var>F</var> of any file type.
+<var>F</var> can be  <var>Text</var> or a typed or untyped <var>File</var> variable.
+After a call to <var>CloseFile</var>, any attempt to write to the file <var>F</var>
+will result in an error.
+</p>
+<p>
+It is most likely introduced to avoid confusion between the regular
+<link id="#rtl.system.Close">Close</link> function and the <var>Close</var> method of <var>TForm</var>
+in the Delphi VCL.
+</p>
+<p>
+for an example, see <link id="AssignFile"/>.
+</p>
+</descr>
+<errors>
+None.
+</errors>
+<seealso>
+<link id="#rtl.system.Close"/>
+<link id="AssignFile"/>
+<link id="#rtl.system.Reset"/>
+<link id="#rtl.system.Rewrite"/>
+<link id="#rtl.system.Append"/>
+</seealso>
+</element>
+
+
+<element name="Freemem">
+<short>Free memory</short>
+<descr>
+<p>
+<var>FreeMem</var> releases the memory reserved by a call to
+<link id="objpasgetmem">GetMem</link>. The (optional) <var>Size</var> parameter is
+ignored, since the object pascal version of <var>GetMem</var> stores the amount
+of memory that was requested.
+</p>
+<p>
+Be sure not to release memory that was not obtained with the <var>Getmem</var>
+call in <file>Objpas</file>. Normally, this should not happen, since objpas
+changes the default memory manager to it's own memory manager.
+</p>
+</descr>
+<errors>
+None.
+</errors>
+<seealso>
+<link id="#rtl.system.Freemem"/>
+<link id="Getmem"/>
+</seealso>
+<example file="refex/ex89"/>
+</element>
+
+
+<element name="Getmem">
+<short>Allocate memory on the heap</short>
+<descr>
+<p>
+<var>GetMem</var> reserves <var>Size</var> bytes of memory on the heap and returns
+a pointer to it in <var>P</var>. <var>Size</var> is stored at offset -4 of the
+result, and is used to release the memory again. <var>P</var> can be a typed or
+untyped pointer.
+</p>
+<p>
+Be sure to release this memory with the <link id="objpasfreemem">FreeMem</link> call
+defined in the <file>objpas</file> unit.
+</p>
+<p>
+For an example, see <link id="objpasfreemem">FreeMem</link>.
+</p>
+</descr>
+<errors>
+In case no more memory is available, and no more memory could be obtained
+from the system a run-time error is triggered.
+</errors>
+<seealso>
+<link id="objpasfreemem">FreeMem</link>
+<link id="Getmem"/>.
+</seealso>
+</element>
+
+
+<element name="GetResourceStringCurrentValue">
+<short>Return current value of resourcestring</short>
+<descr>
+<p>
+<var>GetResourceStringCurrentValue</var> returns the current value of the
+resourcestring in table <var>TableIndex</var> with index <var>StringIndex</var>.
+</p>
+<p>
+The current value depends on the system of internationalization that was
+used, and which language is selected when the program is executed.
+</p>
+</descr>
+<errors>
+If either <var>TableIndex</var> or <var>StringIndex</var> are out of range, then
+a empty string is returned.
+</errors>
+<seealso>
+<link id="SetResourceStrings"/>,
+<link id="GetResourceStringDefaultValue"/>,
+<link id="GetResourceStringHash"/>,
+<link id="GetResourceStringName"/>,
+<link id="ResourceStringTableCount"/>,
+<link id="ResourceStringCount"/>
+</seealso>
+<example file="refex/ex90"/>
+</element>
+
+
+<element name="GetResourceStringDefaultValue">
+<short>Return default (original) value of resourcestring</short>
+<descr>
+<p>
+<var>GetResourceStringDefaultValue</var> returns the default value of the
+resourcestring in table <var>TableIndex</var> with index <var>StringIndex</var>.
+</p>
+<p>
+The default value is the value of the string that appears in the source code
+of the programmer, and is compiled into the program.
+</p>
+</descr>
+<errors>
+If either <var>TableIndex</var> or <var>StringIndex</var> are out of range, then
+a empty string is returned.
+</errors>
+<seealso>
+<link id="SetResourceStrings"/>,
+<link id="GetResourceStringCurrentValue"/>,
+<link id="GetResourceStringHash"/>,
+<link id="GetResourceStringName"/>,
+<link id="ResourceStringTableCount"/>,
+<link id="ResourceStringCount"/>
+</seealso>
+<example file="refex/ex91"/>
+</element>
+
+
+<element name="GetResourceStringHash">
+<short>Return hash value of resource string</short>
+<descr>
+<p>
+<var>GetResourceStringHash</var> returns the hash value associated with the
+resource string in table <var>TableIndex</var>, with index <var>StringIndex</var>.
+</p>
+<p>
+The hash value is calculated from the default value of the resource string
+in a manner that gives the same result as the GNU <file>gettext</file> mechanism.
+It is stored in the resourcestring tables, so retrieval is faster than
+actually calculating the hash for each string.
+</p>
+<p>
+For an example, see <link id="Hash"/>.
+</p>
+</descr>
+<errors>
+If either <var>TableIndex</var> or <var>StringIndex</var> is zero, 0 is returned.
+</errors>
+<seealso>
+<link id="Hash"/>
+<link id="SetResourceStrings"/>,
+<link id="GetResourceStringDefaultValue"/>,
+<link id="GetResourceStringHash"/>,
+<link id="GetResourceStringName"/>,
+<link id="ResourceStringTableCount"/>,
+<link id="ResourceStringCount"/>
+</seealso>
+</element>
+
+
+<element name="GetResourceStringName">
+<short>Return name of resource string.</short>
+<descr>
+<p>
+<var>GetResourceStringName</var> returns the name of the resourcestring in table
+<var>TableIndex</var> with index <var>StringIndex</var>. The name of the string is
+always the unit name in which the string was declared, followed by a period
+and the name of the constant, all in lowercase.
+</p>
+<p>
+If a unit <file>MyUnit</file> declares a resourcestring <var>MyTitle</var> then the
+name returned will be <var>myunit.mytitle</var>. A resourcestring in the program file
+will have the name of the program prepended.
+</p>
+<p>
+The name returned by this function is also the name that is stored in the
+resourcestring file generated by the compiler.
+</p>
+<p>
+Strictly speaking, this information isn't necessary for the functioning
+of the program, it is provided only as a means to easier translation of
+strings.
+</p>
+</descr>
+<errors>
+If either <var>TableIndex</var> or <var>StringIndex</var> is zero, an empty string
+is returned.
+</errors>
+<seealso>
+<link id="SetResourceStrings"/>,
+<link id="GetResourceStringDefaultValue"/>,
+<link id="GetResourceStringHash"/>,
+<link id="GetResourceStringName"/>,
+<link id="ResourceStringTableCount"/>,
+<link id="ResourceStringCount"/>
+</seealso>
+<example file="refex/ex92"/>
+</element>
+
+
+
+<element name="Hash">
+<short>Create GNU Gettext hash value for a string</short>
+<descr>
+<var>Hash</var> calculates the hash value of the string <var>S</var> in a manner that
+is compatible with the GNU gettext hash value for the string. It is the same
+value that is stored in the Resource string tables, and which can be
+retrieved with the <link id="GetResourceStringHash"/> function call.
+</descr>
+<errors>
+ None. In case the calculated hash value should be 0, the returned result
+will be -1.
+</errors>
+<seealso>
+<link id="GetResourceStringHash"/>,
+</seealso>
+<example file="refex/ex93"/>
+</element>
+
+
+<element name="Paramstr">
+<short>Return command-line parameter</short>
+<descr>
+<p>
+<var>ParamStr</var> returns the <var>Param</var>-th command-line parameter as an
+AnsiString. The system unit <link id="Paramstr"/> function limits the result to
+255 characters, and is overridden with this function.
+</p>
+<p>
+The zeroeth command-line parameter contains the path of the executable.
+On some operating systems (BSD) it may be simply the command as typed 
+on the command-line, because the OS does not offer a method to retrieve
+the full binary name.
+</p>
+<p>
+For an example, see <link id="#rtl.system.Paramstr"/>.
+</p>
+</descr>
+<errors>
+In case <var>Param</var> is an invalid value, an empty string is returned.
+</errors>
+<seealso>
+<link id="Paramstr"/>
+</seealso>
+</element>
+
+
+<element name="ReAllocMem">
+<short>Re-allocate memory</short>
+<descr>
+<p>
+<var>ReAllocMem</var> resizes the memory pointed to by <var>P</var> so it has size
+<var>Size</var>. The value of <var>P</var> may change during this operation. 
+The contents of the memory pointed to by <var>P</var> (if any) will be copied to 
+the new location, but may be truncated if the newly allocated memory block
+is smaller in size. If a larger block is allocated, only the used memory is
+initialized, extra memory will not be zeroed out.
+</p>
+<p>
+Note that <var>P</var> may be nil, in that case the behaviour of <var>ReAllocMem</var>
+is equivalent to <link id="Getmem"/>.
+</p>
+</descr>
+<errors>
+If no memory is available then a run-time error will occur.
+</errors>
+<seealso>
+<link id="Getmem"/>
+<link id="Freemem"/>
+</seealso>
+</element>
+
+<element name="ResetResourceTables">
+<short>Restore all resource strings to their declared values</short>
+<descr>
+<p>
+<var>ResetResourceTables</var> resets all resource strings to their default
+(i.e. as in the source code) values.
+</p>
+<p>
+Normally, this should never be called from a user's program. It is called
+in the initialization code of the <file>objpas</file> unit. However, if the
+resourcetables get messed up for some reason, this procedure will fix them
+again.
+</p>
+</descr>
+<errors>
+None.
+</errors>
+<seealso>
+<link id="SetResourceStrings"/>,
+<link id="GetResourceStringDefaultValue"/>,
+<link id="GetResourceStringHash"/>,
+<link id="GetResourceStringName"/>,
+<link id="ResourceStringTableCount"/>,
+<link id="ResourceStringCount"/>
+</seealso>
+</element>
+
+<element name="ResourceStringCount">
+<short>Return number of resource strins in table</short>
+<descr>
+<p>
+<var>ResourceStringCount</var> returns the number of resourcestrings in
+the table with index <var>TableIndex</var>. The strings in a particular table
+are numbered from <var>0</var> to <var>ResourceStringCount-1</var>, i.e. they're zero
+based.
+</p>
+<p>
+For an example, see <link id="GetResourceStringDefaultValue"/>
+</p>
+</descr>
+<errors>
+If an invalid <var>TableIndex</var> is given, <var>-1</var> is returned.
+</errors>
+<seealso>
+<link id="SetResourceStrings"/>,
+<link id="GetResourceStringCurrentValue"/>,
+<link id="GetResourceStringDefaultValue"/>,
+<link id="GetResourceStringHash"/>,
+<link id="GetResourceStringName"/>,
+<link id="ResourceStringTableCount"/>,
+</seealso>
+</element>
+
+
+<element name="ResourceStringTableCount">
+<short>Return number of resource string tables</short>
+<descr>
+<p>
+<var>ResourceStringTableCount</var> returns the number of resource string tables;
+this may be zero if no resource strings are used in a program.
+</p>
+<p>
+The tables are numbered from 0 to <var>ResourceStringTableCount-1</var>, i.e.
+they're zero based.
+</p>
+<p>
+For an example, see <link id="GetResourceStringDefaultValue"/>
+</p>
+</descr>
+<errors>
+</errors>
+<seealso>
+<link id="SetResourceStrings"/>,
+<link id="GetResourceStringDefaultValue"/>,
+<link id="GetResourceStringHash"/>,
+<link id="GetResourceStringName"/>,
+<link id="ResourceStringCount"/>
+</seealso>
+</element>
+
+
+<element name="SetResourceStrings">
+<short>Set values of all resource strings.</short>
+<descr>
+<p>
+<var>SetResourceStrings</var> calls <var>SetFunction</var> for all resourcestrings
+in the resourcestring tables and sets the resourcestring's current value
+to the value returned by <var>SetFunction</var>.
+</p>
+<p>
+The <var>Name</var>,<var>Value</var> and <var>Hash</var> parameters passed to the iterator
+function are the values stored in the tables.
+</p>
+</descr>
+<errors>
+None.
+</errors>
+<seealso>
+<link id="GetResourceStringCurrentValue"/>,
+<link id="GetResourceStringDefaultValue"/>,
+<link id="GetResourceStringHash"/>,
+<link id="GetResourceStringName"/>,
+<link id="ResourceStringTableCount"/>,
+<link id="ResourceStringCount"/>
+</seealso>
+<example file="refex/ex95"/>
+</element>
+
+
+<element name="SetResourceStringValue">
+<short>Set value of a resource string</short>
+<descr>
+<var>SetResourceStringValue</var> assigns <var>Value</var> to the resource string in
+table <var>TableIndex</var> with index <var>StringIndex</var>.
+</descr>
+<errors>
+</errors>
+<seealso>
+<link id="SetResourceStrings"/>,
+<link id="GetResourceStringCurrentValue"/>,
+<link id="GetResourceStringDefaultValue"/>,
+<link id="GetResourceStringHash"/>,
+<link id="GetResourceStringName"/>,
+<link id="ResourceStringTableCount"/>,
+<link id="ResourceStringCount"/>
+</seealso>
+<example file="refex/ex94"/>
+</element>
+
+<!-- constant Visibility: default -->
+<element name="MaxInt">
+<short>Maximum value for <link id="Integer"/> type.</short>
+</element>
+
+<!-- alias type Visibility: default -->
+<element name="integer">
+<short>Redefinition of integer as 32-bit type.</short>
+<descr>
+In <var>OBJPAS</var> mode and in <var>DELPHI</var> mode, an
+<var>Integer</var> has a size of 32 bit. In TP or regular FPC mode, an
+integer is 16 bit.
+</descr>
+</element>
+
+<!-- alias type Visibility: default -->
+<element name="PString">
+<short>Pointer to ansistring type.</short>
+</element>
+
+<!-- array type Visibility: default -->
+<element name="IntegerArray">
+<short>Generic array of <link id="#rtl.objpas.integer">integer</link></short>
+</element>
+
+<!-- alias type Visibility: default -->
+<element name="TIntegerArray">
+<short>Alias for <link id="#rtl.objpas.IntegerArray">IntegerArray</link></short>
+</element>
+
+<!-- pointer type Visibility: default -->
+<element name="PIntegerArray">
+<short>Pointer to <link id="#rtl.objpas.TIntegerArray">TIntegerArray</link> type.</short>
+<descr>
+</descr>
+<seealso>
+</seealso>
+</element>
+
+<!-- array type Visibility: default -->
+<element name="PointerArray">
+<short>Generic Array of pointers.</short>
+</element>
+
+<!-- alias type Visibility: default -->
+<element name="TPointerArray">
+<short>Alias for <link id="#rtl.objpas.PointerArray">PointerArray</link></short>
+</element>
+
+<!-- pointer type Visibility: default -->
+<element name="PPointerArray">
+<short>Pointer to <link id="rtl.objpas.PointerArray">PointerArray</link></short>
+</element>
+
+<!-- array type Visibility: default -->
+<element name="TBoundArray">
+<short>Array of integer, used in interfaces.</short>
+</element>
+
+<!-- pointer type Visibility: default -->
+<element name="PResStringRec">
+<short>Pointer to ansistring (Delphi compatibility).</short>
+</element>
+
+<!-- alias type Visibility: default -->
+<element name="TResStringRec">
+<short>Ansistring record in resource table (Delphi compatibility).</short>
+</element>
+
+<!-- function Visibility: default -->
+<element name="LoadResString">
+<short>Load resource string</short>
+</element>
+</module>
+</package>
+</fpdoc-descriptions>

docs/ports.tex

@@ -1,81 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1997, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA.
-%
-\chapter{The PORTS unit}
-
-\section{Introduction}
-The ports unit implements the \var{port} constructs found in \tp. 
-It uses classes and default array properties to do this.
-
-The unit exists on \linux, \ostwo and \dos. It is implemented only for
-compatibility with \tp. It's usage is discouraged, because using ports
-is not portable programming, and the operating system may not even allow
-it (for instance \windows).
-
-Under \linux, your program must be run as root, or the \var{IOPerm} call
-must be set in order to set appropriate permissions on the port access.
-
-\section{Types,constants and variables}
-
-\subsection{Types}
-The following types are defined to implement the port access.
-\begin{verbatim}
-tport = class
-  protected
-    procedure writeport(p : longint;data : byte);
-    function  readport(p : longint) : byte;
-  public
-    property pp[w : longint] : byte read readport write writeport;default;
-end;
-
-tportw = class
-  protected
-    procedure writeport(p : longint;data : word);
-    function  readport(p : longint) : word;
-  public
-    property pp[w : longint] : word read readport write writeport;default;
-end;
-
-tportl = class
-  Protected
-    procedure writeport(p : longint;data : longint);
-    function  readport(p : longint) : longint;
-  Public
-   property pp[w : Longint] : longint read readport write writeport;default;
-end;
-\end{verbatim}
-Each of these types allows access to the ports using respectively, a byte, a
-word or a longint sized argument.
-
-Since there is a default property for each of this types, a sentence as
-\begin{verbatim}
-  port[221]:=12;
-\end{verbatim}
-Will result in the byte 12 being written to port 221, if port is defined
-as a variable of type \var{tport}
-\subsection{variables}       
-The following variables are defined:
-\begin{verbatim}
-port,
-portb : tport;
-portw : tportw;
-portl : tportl;
-\end{verbatim}
-They allow access to the ports in a \tp compatible way.

docs/printer.tex

@@ -1,72 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1997, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA. 
-%
-\chapter{The PRINTER unit.}
-\label{ch:printerunit}
-
-\FPCexampledir{printex}
-This chapter describes the PRINTER unit for Free Pascal. It was written for
-\dos by Florian Kl\"ampfl, and it was written for \linux by Micha\"el Van 
-Canneyt, and has been ported to \windows and \ostwo as well. 
-Its basic functionality is the same for al supported systems, although there 
-are minor differences on \linux.
-
-The chapter is divided in 2 sections:
-\begin{itemize}
-\item The first section lists types, constants and variables from the
-interface part of the unit.
-\item The second section describes the functions defined in the unit.
-\end{itemize}
-\section {Types, Constants and variables : }
-\begin{verbatim}
-var 
-  lst : text;
-\end{verbatim}
-\var{Lst} is the standard printing device. \\ On \linux, 
-\var{Lst} is set up using \var{AssignLst('/tmp/PID.lst')}. 
-You can change this behaviour at compile time, setting the DefFile constant.
-\section {Procedures and functions}
-\begin{procedure}{AssignLst}
-\Declaration
-Procedure AssignLst  ( Var F : text; ToFile : string[255]);
-
-\Description
- \linux only. \\
- Assigns to F a printing device. ToFile is a string with the following form:
-\begin{itemize}
-\item \var{ '|filename options'}  : This sets up a pipe with the program filename,
-             with the given options, such as in the popen() call.
-\item \var{ 'filename'} : Prints to file filename. Filename can contain the string 'PID'
-              (No Quotes), which will be replaced by the PID of your program.
-              When closing lst, the file will be sent to lpr and deleted.
-              (lpr should be in PATH)
-                
-\item \var {'filename|'} Idem as previous, only the file is NOT sent to lpr, nor is it
-             deleted.
-             (useful for opening /dev/printer or for later printing)
-\end{itemize}
-
-\Errors
- Errors are reported in Linuxerror.
-\SeeAlso
-\seem{lpr}{1}
-\end{procedure}
-
-\FPCexample{printex}

docs/sockets.tex

@@ -1,586 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1997, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA. 
-%
-\chapter{The SOCKETS unit.}
-\label{ch:socketsunit}
-
-\FPCexampledir{sockex}
-This chapter describes the SOCKETS unit for Free Pascal. 
-it was written for \linux by Micha\"el Van Canneyt, and ported to \windows
-by Florian Kl\"ampfl.
-The chapter is divided in 2 sections:
-\begin{itemize}
-\item The first section lists types, constants and variables from the
-interface part of the unit.
-\item The second section describes the functions defined in the unit.
-\end{itemize}
-\section {Types, Constants and variables : }
-The following constants identify the different socket types, as needed in
-the \seef{Socket} call.
-\begin{verbatim}
-SOCK_STREAM     = 1; { stream (connection) socket   }
-SOCK_DGRAM      = 2; { datagram (conn.less) socket  }
-SOCK_RAW        = 3; { raw socket                   }
-SOCK_RDM        = 4; { reliably-delivered message   }
-SOCK_SEQPACKET  = 5; { sequential packet socket     }
-SOCK_PACKET     =10;
-\end{verbatim}
-The following constants determine the socket domain, they are used in the
-\seef{Socket} call.
-\begin{verbatim}
-AF_UNSPEC       = 0;
-AF_UNIX         = 1; { Unix domain sockets          }
-AF_INET         = 2; { Internet IP Protocol         }
-AF_AX25         = 3; { Amateur Radio AX.25          }
-AF_IPX          = 4; { Novell IPX                   }
-AF_APPLETALK    = 5; { Appletalk DDP                }
-AF_NETROM       = 6; { Amateur radio NetROM         }
-AF_BRIDGE       = 7; { Multiprotocol bridge         }
-AF_AAL5         = 8; { Reserved for Werner's ATM    }
-AF_X25          = 9; { Reserved for X.25 project    }
-AF_INET6        = 10; { IP version 6                 }
-AF_MAX          = 12;
-\end{verbatim}
-The following constants determine the protocol family, they are used in the
-\seef{Socket} call.
-\begin{verbatim} 
-PF_UNSPEC       = AF_UNSPEC;
-PF_UNIX         = AF_UNIX;
-PF_INET         = AF_INET;
-PF_AX25         = AF_AX25;
-PF_IPX          = AF_IPX;
-PF_APPLETALK    = AF_APPLETALK;
-PF_NETROM       = AF_NETROM;
-PF_BRIDGE       = AF_BRIDGE;
-PF_AAL5         = AF_AAL5;
-PF_X25          = AF_X25;
-PF_INET6        = AF_INET6;
-PF_MAX          = AF_MAX;   
-\end{verbatim}
-The following types are used to store different kinds of eddresses for the
-\seef{Bind}, \seef{Recv} and \seef{Send} calls.
-\begin{verbatim}  
-TSockAddr = packed Record
-  family:word;
-  data  :array [0..13] of char;
-  end;
-TUnixSockAddr = packed Record
-  family:word;
-  path:array[0..108] of char;
-  end;
-TInetSockAddr = packed Record
-  family:Word;
-  port  :Word;
-  addr  :Cardinal;
-  pad   :array [1..8] of byte; 
-  end;
-\end{verbatim}
-The following type is returned by the \seef{SocketPair} call.
-\begin{verbatim}
-TSockArray = Array[1..2] of Longint;
-\end{verbatim}
-\section {Functions and Procedures}
-\begin{function}{Accept}
-\Declaration
-Function Accept (Sock:Longint;Var Addr;Var Addrlen:Longint) : Longint;
-
-\Description
-\var{Accept} accepts a connection from a socket \var{Sock}, which was
-listening for a connection. If a connection is accepted, a file descriptor
-is returned. On error \var{-1} is returned. The returned socket may NOT 
-be used to accept more connections.  The original socket remains open.
-
-The \var{Accept} call fills the address of the connecting entity in 
-\var{Addr}, and sets its length in \var{Addrlen}. \var{Addr} should 
-be pointing to enough space, and \var{Addrlen} should be set to the 
-amount of space available, prior to the call.
-
-\Errors
-On error, \var{-1} is returned, and errors are reported in 
-\var{SocketError}, and include the following:
-\begin{description}
-\item[SYS\_EBADF]  The socket descriptor is invalid.
-\item[SYS\_ENOTSOCK]  The descriptor is not a socket.
-\item[SYS\_EOPNOTSUPP]  The socket type doesn't support the \var{Listen}
-operation.
-\item[SYS\_EFAULT]  \var{Addr} points outside your address space.
-\item[SYS\_EWOULDBLOCK]  The requested operation would block the process.
-\end{description}
-
-\SeeAlso
-\seef{Listen}, \seef{Connect}
-\end{function}
-
-\FPCexample{socksvr}
-
-\begin{functionl}{Accept}{AltAAccept}
-\Declaration
-Function Accept (Sock:longint;var addr:string;var SockIn,SockOut:text) : Boolean;
-
-\Description
-This is an alternate form of the \seef{Accept} command. It is equivalent
-to subsequently calling the regular \seef{Accept}
-function and the \seep{Sock2Text} function.
-The function returns \var{True} if successfull, \var{False} otherwise.
-
-\Errors
-The errors are those of \seef{Accept}.
-\SeeAlso
-\seef{Accept}
-\end{functionl}
-\begin{functionl}{Accept}{AltBAccept}
-\Declaration
-Function Accept (Sock:longint;var addr:string;var SockIn,SockOut:File) : Boolean;
-
-\Description
- This is an alternate form of the \seef{Accept} command. 
-It is equivalent
-to subsequently calling the regular \seef{Accept} function and the 
-\seep{Sock2File} function.
-The \var{Addr} parameter contains the name of the unix socket file to be
-opened. 
-The function returns \var{True} if successfull, \var{False} otherwise.
-
-\Errors
-The errors are those of \seef{Accept}.
-\SeeAlso
-\seef{Accept}
-\end{functionl}
-\begin{functionl}{Accept}{AltCAccept}
-\Declaration
-Function Accept (Sock:longint;var addr:TInetSockAddr;var SockIn,SockOut:File) : Boolean;
-\Description
- This is an alternate form of the \seef{Accept} command. 
-It is equivalent
-to subsequently calling the regular \seef{Accept} function and the 
-\seep{Sock2File} function.
-The \var{Addr} parameter contains the parameters of the internet socket that
-should be opened.
-The function returns \var{True} if successfull, \var{False} otherwise.
-
-\Errors
-The errors are those of \seef{Accept}.
-\SeeAlso
-\seef{Accept}
-\end{functionl}
-\begin{function}{Bind}
-\Declaration
-Function Bind (Sock:Longint;Var Addr;AddrLen:Longint) : Boolean;
-
-\Description
-\var{Bind} binds the socket \var{Sock} to address \var{Addr}. \var{Addr}
-has length \var{Addrlen}.
-The function returns \var{True} if the call was succesful, \var{False} if
-not.
-
-\Errors
-Errors are returned in \var{SocketError} and include the following:
-\begin{description}
-\item[SYS\_EBADF] The socket descriptor is invalid.
-\item[SYS\_EINVAL] The socket is already bound to an address,
-\item[SYS\_EACCESS] Address is protected and you don't have permission to
-open it.
-\end{description}
-More arrors can be found in the Unix man pages.
-
-\SeeAlso
-\seef{Socket}
-\end{function}
-\begin{functionl}{Bind}{AltBind}
-\Declaration
-Function Bind (Sock:longint;const addr:string) : boolean;
-
-\Description
-This is an alternate form of the \var{Bind} command.
-This form of the \var{Bind} command is equivalent to subsequently 
-calling \seep{Str2UnixSockAddr} and the regular \seef{Bind} function.
-The function returns \var{True} if successfull, \var{False} otherwise.
-
-\Errors
-Errors are those of the regular \seef{Bind} command.
-\SeeAlso
-\seef{Bind}
-\end{functionl}
-\begin{function}{Connect}
-\Declaration
-Function Connect (Sock:Longint;Var Addr;Addrlen:Longint) : Longint;
-
-\Description
-\var{Connect} opens a connection to a peer, whose address is described by
-\var{Addr}. \var{AddrLen} contains the length of the address.
-The type of \var{Addr} depends on the kind of connection you're trying to
-make, but is generally one of \var{TSockAddr} or \var{TUnixSockAddr}.
-
-The \var{Connect} function returns a file descriptor if the call
-was successfull, \var{-1} in case of error.
-\Errors
-On error, \var{-1} is returned and errors are reported in 
-\var{SocketError}.
-\SeeAlso
-\seef{Listen}, \seef{Bind},\seef{Accept}
-\end{function}
-\FPCexample{sockcli}
-\begin{functionl}{Connect}{AltAConnect}
-\Declaration
-Function Connect (Sock:longint;const addr:string;var SockIn,SockOut:text) : Boolean;
-
-\Description
- This is an alternate form of the \seef{Connect} command. 
-It is equivalent to subsequently calling the regular \seef{Connect} 
-function and the  \seep{Sock2Text} function.
-The function returns \var{True} if successfull, \var{False} otherwise.
-
-\Errors
-The errors are those of \seef{Connect}.
-\SeeAlso
-\seef{Connect}
-\end{functionl}
-\begin{functionl}{Connect}{AltBConnect}
-\Declaration
-Function Connect (Sock:longint;const addr:string;var SockIn,SockOut:file) : Boolean;
-
-\Description
- This is an alternate form of the \seef{Connect} command. The parameter
-\var{addr} contains the name of the unix socket file to be opened. 
-It is equivalent to subsequently calling the regular \seef{Connect} 
-function and the  \seep{Sock2File} function.
-The function returns \var{True} if successfull, \var{False} otherwise.
-
-\Errors
-The errors are those of \seef{Connect}.
-\SeeAlso
-\seef{Connect}
-\end{functionl}
-\begin{functionl}{Connect}{AltCConnect}
-\Declaration
-Function Connect (Sock:longint;const addr: TInetSockAddr;var SockIn,SockOut:file) : Boolean;
-
-\Description
- This is another alternate form of the \seef{Connect} command. 
-It is equivalent
-to subsequently calling the regular \seef{Connect} function and the 
-\seep{Sock2File} function. The \var{Addr} parameter contains the parameters
-of the internet socket to connect to.
-The function returns \var{True} if successfull, \var{False} otherwise.
-
-\Errors
-The errors are those of \seef{Connect}.
-\SeeAlso
-\seef{Connect}
-\end{functionl}
-\FPCexample{pfinger}
-
-\begin{function}{GetPeerName}
-\Declaration
-Function GetPeerName (Sock:Longint;Var Addr;Var Addrlen:Longint) : Longint;
-
-\Description
-\var{GetPeerName} returns the name of the entity connected to the 
-specified socket \var{Sock}. The Socket must be connected for this call to
-work. 
-\var{Addr} should point to enough space to store the name, the
-amount of space pointed to should be set in \var{Addrlen}. 
-When the function returns succesfully, \var{Addr} will be filled with the 
-name, and \var{Addrlen} will be set to the length of \var{Addr}.
-
-\Errors
-Errors are reported in \var{SocketError}, and include the following:
-\begin{description}
-\item[SYS\_EBADF] The socket descriptor is invalid.
-\item[SYS\_ENOBUFS] The system doesn't have enough buffers to perform the
-operation.
-\item[SYS\_ENOTSOCK] The descriptor is not a socket.
-\item[SYS\_EFAULT] \var{Addr} points outside your address space.
-\item[SYS\_ENOTCONN] The socket isn't connected.
-\end{description}
-
-\SeeAlso
-\seef{Connect}, \seef{Socket}, \seem{connect}{2}
-\end{function}
-\begin{function}{GetSocketName}
-\Declaration
-Function GetSocketName (Sock:Longint;Var Addr;Var Addrlen:Longint) : Longint;
-
-\Description
-\var{GetSockName} returns the current name of the specified socket
-\var{Sock}. \var{Addr} should point to enough space to store the name, the
-amount of space pointed to should be set in \var{Addrlen}. 
-When the function returns succesfully, \var{Addr} will be filled with the 
-name, and \var{Addrlen} will be set to the length of \var{Addr}.
-\Errors
-Errors are reported in \var{SocketError}, and include the following:
-\begin{description}
-\item[SYS\_EBADF] The socket descriptor is invalid.
-\item[SYS\_ENOBUFS] The system doesn't have enough buffers to perform the
-operation.
-\item[SYS\_ENOTSOCK] The descriptor is not a socket.
-\item[SYS\_EFAULT] \var{Addr} points outside your address space.
-\end{description}
-
-\SeeAlso
-\seef{Bind}
-\end{function}
-\begin{function}{GetSocketOptions}
-\Declaration
-Function GetSocketOptions (Sock,Level,OptName:Longint;Var OptVal;optlen:longint) : Longint;
-
-\Description
-\var{GetSocketOptions} gets the connection options for socket \var{Sock}.
-The socket may be obtained from different levels, indicated by \var{Level},
-which can be one of the following:
-\begin{description}
-\item[SOL\_SOCKET] From the socket itself. 
-\item[XXX] set \var{Level} to \var{XXX}, the protocol number of the protocol
-which should interprete the option.
- \end{description}
-For more information on this call, refer to the unix manual page \seem{getsockopt}{2}.
-
-\Errors
-Errors are reported in \var{SocketError}, and include the following:
-\begin{description}
-\item[SYS\_EBADF] The socket descriptor is invalid.
-\item[SYS\_ENOTSOCK] The descriptor is not a socket.
-\item[SYS\_EFAULT] \var{OptVal} points outside your address space.
-\end{description}
-
-\SeeAlso
-\seef{GetSocketOptions}
-\end{function}
-\begin{function}{Listen}
-\Declaration
-Function Listen (Sock,MaxConnect:Longint) : Boolean;
-
-\Description
-\var{Listen} listens for up to \var{MaxConnect} connections from socket
-\var{Sock}. The socket \var{Sock} must be of type \var{SOCK\_STREAM} or
-\var{Sock\_SEQPACKET}.
-The function returns \var{True} if a connection was accepted, \var{False} 
-if an error occurred.
-
-\Errors
-Errors are reported in \var{SocketError}, and include the following:
-\begin{description}
-\item[SYS\_EBADF] The socket descriptor is invalid.
-\item[SYS\_ENOTSOCK] The descriptor is not a socket.
-\item[SYS\_EOPNOTSUPP] The socket type doesn't support the \var{Listen}
-operation.
-\end{description}
-
-\SeeAlso
-\seef{Socket}, \seef{Bind}, \seef{Connect}
-\end{function}
-\begin{function}{Recv}
-\Declaration
-Function Recv (Sock:Longint;Var Addr;AddrLen,Flags:Longint) : Longint;
-
-\Description
-\var{Recv} reads at most \var{Addrlen} bytes from socket \var{Sock} into
-address \var{Addr}. The socket must be in a connected state.
-\var{Flags} can be one of the following:
-\begin{description}
-\item [1] : Process out-of band data.
-\item [4] : Bypass routing, use a direct interface.
-\item [??] : Wait for full request or report an error.
-\end{description}
-The functions returns the number of bytes actually read from the socket, or
--1 if a detectable error occurred.
-\Errors
-Errors are reported in \var{SocketError}, and include the following:
-\begin{description}
-\item[SYS\_EBADF] The socket descriptor is invalid.
-\item[SYS\_ENOTCONN] The socket isn't connected.
-\item[SYS\_ENOTSOCK] The descriptor is not a socket.
-\item[SYS\_EFAULT] The address is outside your address space.
-\item[SYS\_EMSGSIZE] The message cannot be sent atomically.
-\item[SYS\_EWOULDBLOCK] The requested operation would block the process.
-\item[SYS\_ENOBUFS] The system doesn't have enough free buffers available.
-\end{description}
-
-\SeeAlso
-\seef{Send}
-\end{function}
-\begin{function}{Send}
-\Declaration
-Function Send (Sock:Longint;Var Addr;AddrLen,Flags:Longint) : Longint;
-
-\Description
-\var{Send} sends \var{AddrLen} bytes starting from address \var{Addr}
-to socket \var{Sock}. \var{Sock} must be in a connected state.
-The function returns the number of bytes sent, or -1 if a detectable 
-error occurred.
-\var{Flags} can be one of the following:
-\begin{description}
-\item [1] : Process out-of band data.
-\item [4] : Bypass routing, use a direct interface.
-\end{description}
-
-\Errors
-Errors are reported in \var{SocketError}, and include the following:
-\begin{description}
-\item[SYS\_EBADF] The socket descriptor is invalid.
-\item[SYS\_ENOTSOCK] The descriptor is not a socket.
-\item[SYS\_EFAULT] The address is outside your address space.
-\item[SYS\_EMSGSIZE] The message cannot be sent atomically.
-\item[SYS\_EWOULDBLOCK] The requested operation would block the process.
-\item[SYS\_ENOBUFS] The system doesn't have enough free buffers available.
-\end{description}
-
-\SeeAlso
-\seef{Recv}, \seem{send}{2}
-\end{function}
-\begin{function}{SetSocketOptions}
-\Declaration
-Function SetSocketOptions (Sock,Level,OptName:Longint;Var OptVal;optlen:longint) : Longint;
-
-\Description
-\var{SetSocketOptions} sets the connection options for socket \var{Sock}.
-The socket may be manipulated at different levels, indicated by \var{Level},
-which can be one of the following:
-\begin{description}
-\item[SOL\_SOCKET] To manipulate the socket itself. 
-\item[XXX] set \var{Level} to \var{XXX}, the protocol number of the protocol
-which should interprete the option.
- \end{description}
-For more information on this call, refer to the unix manual page \seem{setsockopt}{2}.
-
-\Errors
-Errors are reported in \var{SocketError}, and include the following:
-\begin{description}
-\item[SYS\_EBADF] The socket descriptor is invalid.
-\item[SYS\_ENOTSOCK] The descriptor is not a socket.
-\item[SYS\_EFAULT] \var{OptVal} points outside your address space.
-\end{description}
-
-\SeeAlso
-\seef{GetSocketOptions}
-\end{function}
-\begin{function}{Shutdown}
-\Declaration
-Function Shutdown (Sock:Longint;How:Longint) : Longint;
-
-\Description
-\var{ShutDown} closes one end of a full duplex socket connection, described
-by \var{Sock}. \var{How} determines how the connection will be shut down,
-and can be one of the following:
-\begin{description}
-\item[0] : Further receives are disallowed.
-\item[1] : Further sends are disallowed.
-\item[2] : Sending nor receiving are allowed.
-\end{description}
-On succes, the function returns 0, on error -1 is returned.
-
-\Errors
-\var{SocketError} is used to report errors, and includes the following:
-\begin{description}
-\item[SYS\_EBADF] The socket descriptor is invalid.
-\item[SYS\_ENOTCONN] The socket isn't connected.
-\item[SYS\_ENOTSOCK] The descriptor is not a socket.
-\end{description}
-
-\SeeAlso
-\seef{Socket}, \seef{Connect}
-\end{function}
-\begin{procedure}{Sock2File}
-\Declaration
-Procedure Sock2File (Sock:Longint;Var SockIn,SockOut:File);
-
-\Description
-\var{Sock2File} transforms a socket \var{Sock} into 2 Pascal file
-descriptors of type \var{File}, one for reading from the socket
-(\var{SockIn}), one for writing to the socket (\var{SockOut}).
-\Errors
-None.
-\SeeAlso
-\seef{Socket}, \seep{Sock2Text}
-\end{procedure}
-\begin{procedure}{Sock2Text}
-\Declaration
-Procedure Sock2Text (Sock:Longint;Var SockIn,SockOut: Text);
-
-\Description
-\var{Sock2Text} transforms a socket \var{Sock} into 2 Pascal file
-descriptors of type \var{Text}, one for reading from the socket
-(\var{SockIn}), one for writing to the socket (\var{SockOut}).
-\Errors
-None.
-\SeeAlso
-\seef{Socket}, \seep{Sock2File}
-\end{procedure}
-\begin{function}{Socket}
-\Declaration
-Function Socket (Domain,SocketType,Protocol:Longint) : Longint;
-
-\Description
-\var{Socket} creates a new socket in domain \var{Domain}, from type
-\var{SocketType} using protocol \var{Protocol}.
-The Domain, Socket type and Protocol can be specified using predefined
-constants (see the section on constants for available constants)
-If succesfull, the function returns a socket descriptor, which can be passed
-to a subsequent \seef{Bind} call. If unsuccesfull, the function returns -1.
-
-\Errors
-Errors are returned in \var{SocketError}, and include the follwing:
-\begin{description}
-\item[SYS\_EPROTONOSUPPORT]
-The protocol type or the specified protocol is not
-supported within this domain.
-\item[SYS\_EMFILE]
-The per-process descriptor table is full.
-\item[SYS\_ENFILE]
-The system file table is full.
-\item[SYS\_EACCESS]
- Permission  to  create  a  socket of the specified
- type and/or protocol is denied.
-\item[SYS\_ENOBUFS]
- Insufficient  buffer  space  is  available.    The
- socket   cannot   be   created   until  sufficient
- resources are freed.
-\end{description}
-\SeeAlso
-\seef{SocketPair}, \seem{socket}{2}
-\end{function}
-
-for an example, see \seef{Accept}.
-
-\begin{function}{SocketPair}
-\Declaration
-Function SocketPair (Domain,SocketType,Protocol:Longint;var Pair:TSockArray) : Longint;
-\Description
-\var{SocketPair} creates 2 sockets in domain \var{Domain}, from type
-\var{SocketType} and using protocol \var{Protocol}.
-The pair is returned in \var{Pair}, and they are indistinguishable.
-The function returns -1 upon error and 0 upon success.
-\Errors
-Errors are reported in \var{SocketError}, and are the same as in \seef{Socket}
-\SeeAlso
-\seep{Str2UnixSockAddr}
-\end{function}
-
-\begin{procedure}{Str2UnixSockAddr}
-\Declaration
-Procedure Str2UnixSockAddr(const addr:string;var t:TUnixSockAddr;var len:longint)
-\Description
-\var{Str2UnixSockAddr} transforms a Unix socket address in a string to a
-\var{TUnixSockAddr} structure which can be passed to the \seef{Bind} call.
-\Errors
-None.
-\SeeAlso
-\seef{Socket}, \seef{Bind}
-\end{procedure}

docs/strings.tex

@@ -1,364 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1997, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA. 
-%
-\chapter{The STRINGS unit.}
-\label{ch:strings}
-\FPCexampledir{stringex}
-
-This chapter describes the \var{STRINGS} unit for \fpc. This unit is system
-independent, and therefore works on all supported platforms.
-
-Since the unit only provides some procedures and functions, there is
-only one section, which gives the declarations of these functions, together
-with an explanation. 
-
-\section{Functions and procedures.}
-
-\begin{function}{StrAlloc}
-\Declaration
-Function StrAlloc (Len : Longint) : PChar;
-\Description
-\var{StrAlloc} reserves memory on the heap for a string with length \var{Len},
-terminating \var{\#0} included, and returns a pointer to it.
-\Errors
-If there is not enough memory, a run-time error occurs.
-\SeeAlso
-\seef{StrNew}, \seef{StrPCopy}.
-\end{function}
-
-
-\begin{function}{StrCat}
-\Declaration
-Function StrCat (Dest,Source : PChar) : PChar;
-\Description
-Attaches \var{Source} to \var{Dest} and returns \var{Dest}.
-\Errors
-No length checking is performed.
-\SeeAlso
-\seem{Concat}{}
-\end{function}
-
-\FPCexample{ex11}
-
-\begin{function}{StrComp}
-\Declaration
-Function StrComp (S1,S2 : PChar) : Longint;
-\Description
-Compares the null-terminated strings \var{S1} and \var{S2}.
-The result is 
-\begin{itemize}
-\item A negative \var{Longint} when \var{S1<S2}.
-\item 0 when \var{S1=S2}.
-\item A positive \var{Longint} when \var{S1>S2}.
-\end{itemize}
-\Errors
-None.
-\SeeAlso
-\seef{StrLComp}, \seef{StrIComp}, \seef{StrLIComp}
-\end{function}
-
-For an example, see \seef{StrLComp}.
-
-\begin{function}{StrCopy}
-\Declaration
-Function StrCopy (Dest,Source : PChar) : PChar;
-\Description
-Copy the null terminated string in \var{Source} to \var{Dest}, and
-returns a pointer to \var{Dest}. \var{Dest} needs enough room to contain
-\var{Source}, i.e. \var{StrLen(Source)+1} bytes.
-\Errors
-No length checking is performed.
-\SeeAlso
- \seef{StrPCopy}, \seef{StrLCopy}, \seef{StrECopy}
-\end{function}
-
-\FPCexample{ex4}
-
-\begin{procedure}{StrDispose}
-\Declaration
-Procedure StrDispose (P : PChar);
-\Description
-Removes the string in \var{P} from the heap and releases the memory.
-\Errors
-None.
-\SeeAlso
-\seem{Dispose}{}, \seef{StrNew}
-\end{procedure}
-
-\FPCexample{ex17}
-
-\begin{function}{StrECopy}
-\Declaration
-Function StrECopy (Dest,Source : PChar) : PChar;
-\Description
-Copies the Null-terminated string in \var{Source} to \var{Dest}, and
-returns a pointer to the end (i.e. the terminating Null-character) of the
-copied string.
-\Errors
-No length checking is performed.
-\SeeAlso
-\seef{StrLCopy}, \seef{StrCopy}
-\end{function}
-
-\FPCexample{ex6}
-
-\begin{function}{StrEnd}
-\Declaration
-Function StrEnd (P : PChar) : PChar;
-\Description
-Returns a pointer to the end of \var{P}. (i.e. to the terminating
-null-character.
-\Errors
-None.
-\SeeAlso
-\seef{StrLen}
-\end{function}
-
-\FPCexample{ex7}
-
-\begin{function}{StrIComp}
-\Declaration
-Function StrIComp (S1,S2 : PChar) : Longint;
-\Description
-Compares the null-terminated strings \var{S1} and \var{S2}, ignoring case.
-The result is 
-\begin{itemize}
-\item A negative \var{Longint} when \var{S1<S2}.
-\item 0 when \var{S1=S2}.
-\item A positive \var{Longint} when \var{S1>S2}.
-\end{itemize}
-\Errors
-None.
-\SeeAlso
-\seef{StrLComp}, \seef{StrComp}, \seef{StrLIComp}
-\end{function}
-
-\FPCexample{ex8}
-
-\begin{function}{StrLCat}
-\Declaration
-Function StrLCat (Dest,Source : PChar; MaxLen : Longint) : PChar;
-\Description
-Adds \var{MaxLen} characters from \var{Source} to \var{Dest}, and adds a
-terminating null-character. Returns \var{Dest}.
-\Errors
-None.
-\SeeAlso
-\seef{StrCat}
-\end{function}
-
-\FPCexample{ex12}
-
-\begin{function}{StrLComp}
-\Declaration
-Function StrLComp (S1,S2 : PChar; L : Longint) : Longint;
-\Description
-Compares maximum \var{L} characters of the null-terminated strings 
-\var{S1} and \var{S2}. 
-The result is 
-\begin{itemize}
-\item A negative \var{Longint} when \var{S1<S2}.
-\item 0 when \var{S1=S2}.
-\item A positive \var{Longint} when \var{S1>S2}.
-\end{itemize}
-\Errors
-None.
-\SeeAlso
-\seef{StrComp}, \seef{StrIComp}, \seef{StrLIComp}
-\end{function}
-
-\FPCexample{ex8}
-
-\begin{function}{StrLCopy}
-\Declaration
-Function StrLCopy (Dest,Source : PChar; MaxLen : Longint) : PChar;
-\Description
-Copies \var{MaxLen} characters from \var{Source} to \var{Dest}, and makes
-\var{Dest} a null terminated string. 
-\Errors
-No length checking is performed.
-\SeeAlso
-\seef{StrCopy}, \seef{StrECopy}
-\end{function}
-
-\FPCexample{ex5}
-
-\begin{function}{StrLen}
-\Declaration
-Function StrLen (p : PChar) : Longint;
-\Description
-Returns the length of the null-terminated string \var{P}.
-\Errors
-None.
-\SeeAlso
-\seem{Length}{}
-\end{function}
-
-\FPCexample{ex1}
-
-\begin{function}{StrLIComp}
-\Declaration
-Function StrLIComp (S1,S2 : PChar; L : Longint) : Longint;
-\Description
-Compares maximum \var{L} characters of the null-terminated strings \var{S1} 
-and \var{S2}, ignoring case.
-The result is 
-\begin{itemize}
-\item A negative \var{Longint} when \var{S1<S2}.
-\item 0 when \var{S1=S2}.
-\item A positive \var{Longint} when \var{S1>S2}.
-\end{itemize}
-\Errors
-None.
-\SeeAlso
-\seef{StrLComp}, \seef{StrComp}, \seef{StrIComp}
-\end{function}
-
-For an example, see \seef{StrIComp}
-
-\begin{function}{StrLower}
-\Declaration
-Function StrLower (P : PChar) : PChar;
-\Description
-Converts \var{P} to an all-lowercase string. Returns \var{P}.
-\Errors
-None.
-\SeeAlso
-\seem{Upcase}{}, \seef{StrUpper}
-\end{function}
-
-\FPCexample{ex14}
-
-\begin{function}{StrMove}
-\Declaration
-Function StrMove (Dest,Source : PChar; MaxLen : Longint) : PChar;
-\Description
-Copies \var{MaxLen} characters from \var{Source} to \var{Dest}. No
-terminating null-character is copied.
-Returns \var {Dest}.
-\Errors
-None.
-\SeeAlso
-\seef{StrLCopy}, \seef{StrCopy}
-\end{function}
-
-\FPCexample{ex10}
-
-\begin{function}{StrNew}
-\Declaration
-Function StrNew (P : PChar) : PChar;
-\Description
-Copies \var{P} to the Heap, and returns a pointer to the copy.
-\Errors
-Returns \var{Nil} if no memory was available for the copy.
-\SeeAlso
-\seem{New}{}, \seef{StrCopy}, \seep{StrDispose}
-\end{function}
-
-\FPCexample{ex16}
-
-\begin{function}{StrPas}
-\Declaration
-Function StrPas (P : PChar) : String;
-\Description
-Converts a null terminated string in \var{P} to a Pascal string, and returns
-this string. The string is truncated at 255 characters.
-\Errors
-None.
-\SeeAlso
- \seef{StrPCopy}
-\end{function}
-
-\FPCexample{ex3}
-
-\begin{function}{StrPCopy}
-\Declaration
-Function StrPCopy (Dest : PChar; Const Source : String) : PChar;
-\Description
-Converts the Pascal string in \var{Source} to a Null-terminated 
-string, and copies it to \var{Dest}. \var{Dest} needs enough room to contain
-the string \var{Source}, i.e. \var{Length(Source)+1} bytes.
-\Errors
-No length checking is performed.
-\SeeAlso
- \seef{StrPas}
-\end{function}
-
-\FPCexample{ex2}
-
-\begin{function}{StrPos}
-\Declaration
-Function StrPos (S1,S2 : PChar) : PChar;
-\Description
-Returns a pointer to the first occurrence of \var{S2} in \var{S1}.
-If \var{S2} does not occur in \var{S1}, returns \var{Nil}.
-\Errors
-None.
-\SeeAlso
-\seem{Pos}{}, \seef{StrScan}, \seef{StrRScan}
-\end{function}
-
-\FPCexample{ex15}
-
-\begin{function}{StrRScan}
-\Declaration
-Function StrRScan (P : PChar; C : Char) : PChar;
-\Description
-Returns a pointer to the last occurrence of the character \var{C} in the
-null-terminated string \var{P}. If \var{C} does not occur, returns
-\var{Nil}.
-\Errors
-None.
-\SeeAlso
-\seem{Pos}{}, \seef{StrScan}, \seef{StrPos}
-\end{function}
-
-
-For an example, see \seef{StrScan}.
-
-
-\begin{function}{StrScan}
-\Declaration
-Function StrScan (P : PChar; C : Char) : PChar;
-\Description
-Returns a pointer to the first occurrence of the character \var{C} in the
-null-terminated string \var{P}. If \var{C} does not occur, returns
-\var{Nil}.
-
-\Errors
-None.
-\SeeAlso
-\seem{Pos}{}, \seef{StrRScan}, \seef{StrPos}
-\end{function}
-
-\FPCexample{ex13}
-
-\begin{function}{StrUpper}
-\Declaration
-Function StrUpper (P : PChar) : PChar;
-\Description
-Converts \var{P} to an all-uppercase string. Returns \var{P}.
-\Errors
-None.
-\SeeAlso
-\seem{Upcase}{}, \seef{StrLower}
-\end{function}
-
-For an example, see \seef{StrLower}

docs/sysutils.tex

@@ -1,2814 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1999, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA.
-%
-\chapter{The SYSUTILS unit.}
-\FPCexampledir{sysutex}
-
-This chapter describes the \file{sysutils} unit. The \file{sysutils} unit
-was largely written by Gertjan Schouten, and completed by Micha\"el Van Canneyt.
-It aims to be compatible to the Delphi \file{sysutils} unit, but in contrast
-with  the latter, it is designed to work on multiple platforms. It is implemented
-on all supported platforms.
-
-This chapter starts out with a definition of all types and constants
-that are defined, followed by an overview of functions grouped by
-functionality, and lastly the complete explanation of each function.
-
-\section{Constants and types}
-The following general-purpose types are defined:
-\begin{verbatim}
-tfilename = string;
-
-tsyscharset = set of char;
-tintegerset = set of 0..sizeof(integer)*8-1;
-
-longrec = packed record
-   lo,hi : word;
-end;
-
-wordrec = packed record
-   lo,hi : byte;
-end;
-
-TMethod = packed record
-  Code, Data: Pointer;
-end;
-\end{verbatim}
-The use and meaning of these types should be clear, so no extra information
-will be provided here.
-
-The following general-purpose constants are defined:
-\begin{verbatim}
-const
-   SecsPerDay = 24 * 60 * 60; // Seconds and milliseconds per day
-   MSecsPerDay = SecsPerDay * 1000;
-   DateDelta = 693594;        // Days between 1/1/0001 and 12/31/1899
-   Eoln = #10;
-\end{verbatim}
-The following types are used frequently in date and time functions.
-They are the same on all platforms.
-\begin{verbatim}
-type
-   TSystemTime = record
-      Year, Month, Day: word;
-      Hour, Minute, Second, MilliSecond: word;
-   end ;
-
-   TDateTime = double;
-
-   TTimeStamp = record
-      Time: integer;   { Number of milliseconds since midnight }
-      Date: integer;   { One plus number of days since 1/1/0001 }
-   end ;
-\end{verbatim}
-The following type is used in the \seef{FindFirst},\seef{FindNext}
-and \seepl{FindClose}{FindCloseSys} functions. The \var{win32} version differs from
-the other versions. If code is to be portable, that part  shouldn't
-be used.
-\begin{verbatim}
-Type
-  THandle = Longint;
-  TSearchRec = Record
-    Time,Size, Attr : Longint;
-    Name : TFileName;
-    ExcludeAttr : Longint;
-    FindHandle : THandle;
-    {$ifdef Win32}
-    FindData : TWin32FindData;
-    {$endif}
-    end;
-\end{verbatim}
-The following constants are file-attributes that need to be matched in the
-findfirst call.
-\begin{verbatim}
-Const
-  faReadOnly  = $00000001;
-  faHidden    = $00000002;
-  faSysFile   = $00000004;
-  faVolumeId  = $00000008;
-  faDirectory = $00000010;
-  faArchive   = $00000020;
-  faAnyFile   = $0000003f;
-\end{verbatim}
-The following constants can be used in the \seef{FileOpen} call.
-\begin{verbatim}
-Const
-  fmOpenRead       = $0000;
-  fmOpenWrite      = $0001;
-  fmOpenReadWrite  = $0002;
-\end{verbatim}
-The following constants can be used in the \seef{FileSeek} call.
-\begin{verbatim}
-Const
-  fsFromBeginning = 0;
-  fsFromCurrent   = 1;
-  fsFromEnd       = 2;
-
-\end{verbatim}
-The following variables are used in the case translation routines.
-\begin{verbatim}
-type
-   TCaseTranslationTable = array[0..255] of char;
-var
-   UpperCaseTable: TCaseTranslationTable;
-   LowerCaseTable: TCaseTranslationTable;
-\end{verbatim}
-The initialization code of the \file{sysutils} unit fills these
-tables with the appropriate values. For the win32 and go32v2
-versions, this information is obtained from the operating system.
-
-The following constants control the formatting of dates.
-For the Win32 version of the \file{sysutils} unit, these
-constants are set according to the internationalization
-settings of Windows by the initialization code of the unit.
-\begin{verbatim}
-Const
-   DateSeparator: char = '-';
-   ShortDateFormat: string = 'd/m/y';
-   LongDateFormat: string = 'dd" "mmmm" "yyyy';
-   ShortMonthNames: array[1..12] of string[128] =
-     ('Jan','Feb','Mar','Apr','May','Jun',
-      'Jul','Aug','Sep','Oct','Nov','Dec');
-   LongMonthNames: array[1..12] of string[128] =
-     ('January','February','March','April',
-      'May','June','July','August',
-      'September','October','November','December');
-   ShortDayNames: array[1..7] of string[128] =
-     ('Sun','Mon','Tue','Wed','Thu','Fri','Sat');
-   LongDayNames: array[1..7] of string[128] =
-     ('Sunday','Monday','Tuesday','Wednesday',
-       'Thursday','Friday','Saturday');
-\end{verbatim}
-
-The following constants control the formatting of times.
-For the Win32 version of the \file{sysutils} unit, these
-constants are set according to the internationalization
-settings of Windows by the initialization code of the unit.
-\begin{verbatim}
-Const
-   ShortTimeFormat: string = 'hh:nn';
-   LongTimeFormat: string = 'hh:nn:ss';
-   TimeSeparator: char = ':';
-   TimeAMString: string[7] = 'AM';
-   TimePMString: string[7] = 'PM';
-\end{verbatim}
-
-The following constants control the formatting of currencies
-and numbers. For the Win32 version of the \file{sysutils} unit,
-these  constants are set according to the internationalization
-settings of Windows by the initialization code of the unit.
-\begin{verbatim}
-Const
-  DecimalSeparator : Char = '.';
-  ThousandSeparator : Char = ',';
-  CurrencyDecimals : Byte = 2;
-  CurrencyString : String[7] = '$';
-  { Format to use when formatting currency :
-    0 = $1        1 = 1$         2 = $ 1      3 = 1 $
-    4 = Currency string replaces decimal indicator.
-        e.g. 1$50
-   }
-  CurrencyFormat : Byte = 1;
-  { Same as above, only for negative currencies:
-    0 = ($1)
-    1 = -$1
-    2 = $-1
-    3 = $1-
-    4 = (1$)
-    5 = -1$
-    6 = 1-$
-    7 = 1$-
-    8 = -1 $
-    9 = -$ 1
-    10 = $ 1-
-   }
-  NegCurrFormat : Byte = 5;
-\end{verbatim}
-The following types are used in various string functions.
-\begin{verbatim}
-type
-   PString = ^String;
-   TFloatFormat = (ffGeneral, ffExponent, ffFixed, ffNumber, ffCurrency);
-\end{verbatim}
-The following constants are used in the file name handling routines. Do not
-use a slash of backslash character directly as a path separator; instead
-use the \var{OsDirSeparator} character.
-\begin{verbatim}
-Const
-  DirSeparators : set of char = ['/','\'];
-{$ifdef unix}
-  OSDirSeparator = '/';
-{$else}
-  OsDirSeparator = '\';
-{$endif}
-\end{verbatim}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Functions and procedures by category
-\section{Function list by category}
-What follows is a listing of the available functions, grouped by category.
-For each function there is a reference to the page where you can find the
-function.
-
-\subsection{String functions}
-Functions for handling strings.
-\begin{funclist}
-\funcref{AnsiCompareStr}{Compare two strings}
-\funcref{AnsiCompareText}{Compare two strings, case insensitive}
-\funcref{AnsiExtractQuotedStr}{Removes quotes from string}
-\funcref{AnsiLastChar}{Get last character of string}
-\funcref{AnsiLowerCase}{Convert string to all-lowercase}
-\funcref{AnsiQuotedStr}{Qoutes a string}
-\funcref{AnsiStrComp}{Compare strings case-sensitive}
-\funcref{AnsiStrIComp}{Compare strings case-insensitive}
-\funcref{AnsiStrLComp}{Compare L characters of strings case sensitive}
-\funcref{AnsiStrLIComp}{Compare L characters of strings case insensitive}
-\funcref{AnsiStrLastChar}{Get last character of string}
-\funcref{AnsiStrLower}{Convert string to all-lowercase}
-\funcref{AnsiStrUpper}{Convert string to all-uppercase}
-\funcref{AnsiUpperCase}{Convert string to all-uppercase}
-\procref{AppendStr}{Append 2 strings}
-\procref{AssignStr}{Assign value of strings on heap}
-\funcref{CompareStr}{Compare two strings case sensitive}
-\funcref{CompareText}{Compare two strings case insensitive}
-\procrefl{DisposeStr}{DisposeStrSys}{Remove string from heap}
-\funcref{IsValidIdent}{Is string a valid pascal identifier}
-\funcref{LastDelimiter}{Last occurance of character in a string}
-\funcref{LeftStr}{Get first N characters of a string}
-\funcref{LoadStr}{Load string from resources}
-\funcref{LowerCase}{Convert string to all-lowercase}
-\funcrefl{NewStr}{NewStrSys}{Allocate new string on heap}
-\funcref{RightStr}{Get last N characters of a string}
-\funcrefl{StrAlloc}{StrAllocSys}{Allocate memory for string}
-\funcref{StrBufSize}{Reserve memory for a string}
-\procrefl{StrDispose}{StrDisposeSys}{Remove string from heap}
-\funcrefl{StrPas}{StrPasSys}{Convert PChar to pascal string}
-\funcrefl{StrPCopy}{StrPCopySys}{Copy pascal string}
-\funcrefl{StrPLCopy}{StrPLCopySys}{Copy N bytes of pascal string}
-\funcref{UpperCase}{Convert string to all-uppercase}
-\end{funclist}
-
-\subsection{Formatting strings}
-Functions for formatting strings.
-\begin{funclist}
-\funcref{AdjustLineBreaks}{Convert line breaks to line breaks for system}
-\funcref{FormatBuf}{Format a buffer}
-\funcref{Format}{Format arguments in string}
-\procref{FmtStr}{Format buffer}
-\funcref{QuotedStr}{Quote a string}
-\funcref{StrFmt}{Format arguments in a string}
-\funcref{StrLFmt}{Format maximum L characters in a string}
-\funcref{TrimLeft}{Remove whitespace at the left of a string}
-\funcref{TrimRight}{Remove whitespace at the right of a string}
-\funcref{Trim}{Remove whitespace at both ends of a string}
-\end{funclist}
-
-\subsection{File input/output routines}
-Functions for reading/writing to file.
-\begin{funclist}
-\funcref{FileCreate}{Create a file and return handle}
-\funcref{FileOpen}{Open file end return handle}
-\funcref{FileRead}{Read from file}
-\funcref{FileSeek}{Set file position}
-\funcref{FileTruncate}{Truncate file length}
-\funcref{FileWrite}{Write to file}
-\procref{FileClose}{Close file handle}
-\end{funclist}
-
-\subsection{File handling routines}
-Functions for file manipulation.
-\begin{funclist}
-\funcref{AddDisk}{Add sisk to list of disk drives}
-\funcref{ChangeFileExt}{Change extension of file name}
-\funcref{CreateDir}{Create a directory}
-\funcref{DeleteFile}{Delete a file}
-\funcrefl{DiskFree}{DiskFreeSys}{Free space on disk}
-\funcrefl{DiskSize}{DiskSizeSys}{Total size of disk}
-\funcref{ExpandFileName}{Create full file name}
-\funcref{ExpandUNCFileName}{Create full UNC file name}
-\funcref{ExtractFileDir}{Extract directory part of filename}
-\funcref{ExtractFileDrive}{Extract drive part of filename}
-\funcref{ExtractFileExt}{Extract extension part of filename}
-\funcref{ExtractFileName}{Extract name part of filename}
-\funcref{ExtractFilePath}{Extrct path part of filename}
-\funcref{ExtractRelativePath}{Construct relative path between two files}
-\funcref{FileAge}{Return file age}
-\funcref{FileDateToDateTime}{Convert file date to system date}
-\funcref{FileExists}{Determine whether a file exists on disk}
-\funcref{FileGetAttr}{Get attributes of file}
-\funcref{FileGetDate}{Get date of last file modification}
-\funcref{FileSearch}{Search for file in path}
-\funcrefl{FileSetAttr}{FileSetAttr}{Get file attributes}
-\funcrefl{FileSetDate}{FileSetDate}{Get file dates}
-\funcref{FindFirst}{Start finding a file}
-\funcref{FindNext}{Find next file}
-\funcref{GetCurrentDir}{Return current working directory}
-\funcref{RemoveDir}{Remove a directory from disk}
-\funcref{RenameFile}{Rename a file on disk}
-\funcref{SetCurrentDir}{Set current working directory}
-\funcref{SetDirSeparators}{Set directory separator characters}
-\procrefl{FindClose}{FindCloseSys}{Stop searching a file}
-\procref{DoDirSeparators}{Replace directory separator characters}
-\end{funclist}
-
-\subsection{Date/time routines}
-Functions for date and time handling.
-\begin{funclist}
-\funcref{DateTimeToFileDate}{Convert DateTime type to file date}
-\funcref{DateTimeToStr}{Construct string representation of DateTime}
-\procref{DateTimeToString}{Construct string representation of DateTime}
-\procref{DateTimeToSystemTime}{Convert DateTime to system time}
-\funcref{DateTimeToTimeStamp}{Convert DateTime to timestamp}
-\funcref{DateToStr}{Construct string representation of date}
-\funcref{Date}{Get current date}
-\funcref{DayOfWeek}{Get day of week}
-\procref{DecodeDate}{Decode DateTime to year month and day}
-\procref{DecodeTime}{Decode DateTime to hours, minutes and seconds}
-\funcref{EncodeDate}{Encode year, day and month to DateTime}
-\funcref{EncodeTime}{Encode hours, minutes and seconds to DateTime}
-\funcref{FormatDateTime}{Return string representation of DateTime}
-\funcref{IncMonth}{Add 1 to month}
-\funcref{IsLeapYear}{Determine if year is leap year}
-\funcref{MSecsToTimeStamp}{Convert nr of milliseconds to timestamp}
-\funcref{Now}{Get current date and time}
-\funcref{StrToDateTime}{Convert string to DateTime}
-\funcref{StrToDate}{Convert string to date}
-\funcref{StrToTime}{Convert string to time}
-\funcref{SystemTimeToDateTime}{Convert system time to datetime}
-\funcref{TimeStampToDateTime}{Convert time stamp to DateTime}
-\funcref{TimeStampToMSecs}{Convert Timestamp to number of millicseconds}
-\funcref{TimeToStr}{return string representation of Time}
-\funcref{Time}{Get current tyme}
-\end{funclist}
-
-\section{Miscellaneous conversion routines}
-Functions for various conversions.
-\begin{funclist}
-\funcref{BCDToInt}{Convert BCD number to integer}
-\funcref{CompareMem}{Compare two memory regions}
-\funcref{FloatToStrF}{Convert float to formatted string}
-\funcref{FloatToStr}{Convert float to string}
-\funcref{FloatToText}{Convert float to string}
-\funcref{FormatFloat}{Format a floating point value}
-\funcref{GetDirs}{Split string in list of directories}
-\funcref{IntToHex}{return hexadecimal representation of integer}
-\funcref{IntToStr}{return decumal representation of integer}
-\funcref{StrToIntDef}{Convert string to integer with default value}
-\funcref{StrToInt}{Convert string to integer}
-\funcref{StrToFloat}{Convert string to float}
-\funcref{TextToFloat}{Convert null-terminated string to float}
-\end{funclist}
-
-\section{Date and time functions}
-
-\subsection{Date and time formatting characters}
-\label{se:formatchars}
-
-Various date and time formatting routines accept a format string.
-to format the date and or time. The following characters can be used
-to control the date and time formatting:
-\begin{description}
-\item[c] : shortdateformat + ' ' + shorttimeformat
-\item[d] : day of month
-\item[dd] : day of month (leading zero)
-\item[ddd] : day of week (abbreviation)
-\item[dddd] : day of week (full)
-\item[ddddd] : shortdateformat
-\item[dddddd] : longdateformat
-\item[m] : month
-\item[mm] : month (leading zero)
-\item[mmm] : month (abbreviation)
-\item[mmmm] : month (full)
-\item[y] : year (four digits)
-\item[yy] : year (two digits)
-\item[yyyy] : year (with century)
-\item[h] : hour
-\item[hh] : hour (leading zero)
-\item[n] : minute
-\item[nn] : minute (leading zero)
-\item[s] : second
-\item[ss] : second (leading zero)
-\item[t] : shorttimeformat
-\item[tt] : longtimeformat
-\item[am/pm] : use 12 hour clock and display am and pm accordingly
-\item[a/p] : use 12 hour clock and display a and p accordingly
-\item[/] : insert date seperator
-\item[:] : insert time seperator
-\item["xx"] : literal text
-\item['xx'] : literal text
-\end{description}
-
-\begin{type}{TDateTime}
-\Declaration
-  TDateTime = Double;
-\Description
-Many functions return or require a \var{TDateTime} type, which contains
-a date and time in encoded form. The date and time are converted to a double
-as follows:
-\begin{itemize}
-\item The date part is stored in the integer part of the double as the
-number of days passed since January 1, 1900.
-\item The time part is stored in the fractional part of the double, as
-the number of milliseconds passed since midnight (00:00), divided by the
-total number of milliseconds in a day.
-\end{itemize}
-\end{type}
-
-\begin{function}{Date}
-\Declaration
-Function Date: TDateTime;
-\Description
-\var{Date} returns the current date in \var{TDateTime} format.
-For more information about the \var{TDateTime} type, see \seetype{TDateTime}.
-\Errors
-None.
-\SeeAlso
-\seef{Time},\seef{Now}, \seetype{TDateTime}.
-\end{function}
-
-\FPCexample{ex1}
-
-
-\begin{function}{DateTimeToFileDate}
-\Declaration
-Function DateTimeToFileDate(DateTime : TDateTime) : Longint;
-\Description
-\var{DateTimeToFileDate} function converts a date/time indication in
-\var{TDateTime} format to a filedate function, such as returned for
-instance by the \seef{FileAge} function.
-\Errors
-None.
-\SeeAlso
-\seef{Time}, \seef{Date}, \seef{FileDateToDateTime},
-\seep{DateTimeToSystemTime}, \seef{DateTimeToTimeStamp}
-\end{function}
-
-\FPCexample{ex2}
-
-
-\begin{function}{DateTimeToStr}
-\Declaration
-Function DateTimeToStr(DateTime: TDateTime): string;
-\Description
-\var{DateTimeToStr} returns a string representation of
-\var{DateTime} using the formatting specified in
-\var{ShortDateTimeFormat}. It corresponds to a call to
-\var{FormatDateTime('c',DateTime)} (see \sees{formatchars}).
-\Errors
-None.
-\SeeAlso
-\seef{FormatDateTime}, \seetype{TDateTime}.
-\end{function}
-
-\FPCexample{ex3}
-
-
-\begin{procedure}{DateTimeToString}
-\Declaration
-Procedure DateTimeToString(var Result: string; const FormatStr: string; const DateTime: TDateTime);
-\Description
-\var{DateTimeToString} returns in \var{Result} a string representation of
-\var{DateTime} using the formatting specified in \var{FormatStr}.
-
-for a list of characters that can be used in the \var{FormatStr} formatting
-string, see \sees{formatchars}.
-\Errors
-In case a wrong formatting character is found, an \var{EConvertError} is
-raised.
-\SeeAlso
-\seef{FormatDateTime}, \sees{formatchars}.
-\end{procedure}
-
-\FPCexample{ex4}
-
-
-\begin{procedure}{DateTimeToSystemTime}
-\Declaration
-Procedure DateTimeToSystemTime(DateTime: TDateTime; var SystemTime: TSystemTime);
-\Description
-\var{DateTimeToSystemTime} converts a date/time pair in \var{DateTime}, with
-\var{TDateTime} format to a system time \var{SystemTime}.
-\Errors
-None.
-\SeeAlso
-\seef{DateTimeToFileDate}, \seef{SystemTimeToDateTime},
-\seef{DateTimeToTimeStamp}
-\end{procedure}
-
-\FPCexample{ex5}
-
-
-\begin{function}{DateTimeToTimeStamp}
-\Declaration
-Function DateTimeToTimeStamp(DateTime: TDateTime): TTimeStamp;
-\Description
-\var{DateTimeToSystemTime} converts a date/time pair in \var{DateTime}, with
-\var{TDateTime} format to a \var{TTimeStamp} format.
-\Errors
-None.
-\SeeAlso
-\seef{DateTimeToFileDate}, \seef{SystemTimeToDateTime},
-\seep{DateTimeToSystemTime}
-\end{function}
-
-\FPCexample{ex6}
-
-
-\begin{function}{DateToStr}
-\Declaration
-Function DateToStr(Date: TDateTime): string;
-\Description
-\var{DateToStr} converts \var{Date} to a string representation. It uses
-\var{ShortDateFormat} as it's formatting string. It is hence completely
-equivalent to a \var{FormatDateTime('ddddd', Date)}.
-\Errors
-None.
-\SeeAlso
-\seef{TimeToStr}, \seef{DateTimeToStr}, \seef{FormatDateTime},
-\seef{StrToDate}
-\end{function}
-
-
-\FPCexample{ex7}
-
-
-\begin{function}{DayOfWeek}
-\Declaration
-Function DayOfWeek(DateTime: TDateTime): integer;
-\Description
-\var{DayOfWeek} returns the day of the week from \var{DateTime}.
-\var{Sunday} is counted as day 1, \var{Saturday} is counted as
-day 7. The result of \var{DayOfWeek} can serve as an index to
-the \var{LongDayNames} constant array, to retrieve the name of
-the day.
-\Errors
-None.
-\SeeAlso
-\seef{Date}, \seef{DateToStr}
-\end{function}
-
-
-\FPCexample{ex8}
-
-
-\begin{procedure}{DecodeDate}
-\Declaration
-Procedure DecodeDate(Date: TDateTime; var Year, Month, Day: word);
-\Description
-\var{DecodeDate} decodes the Year, Month and Day stored in \var{Date},
-and returns them in the \var{Year}, \var{Month} and \var{Day} variables.
-\Errors
-None.
-\SeeAlso
-\seef{EncodeDate}, \seep{DecodeTime}.
-\end{procedure}
-
-\FPCexample{ex9}
-
-
-
-\begin{procedure}{DecodeTime}
-\Declaration
-Procedure DecodeTime(Time: TDateTime; var Hour, Minute, Second, MilliSecond: word);
-\Description
-\var{DecodeDate} decodes the hours, minutes, second and milliseconds stored
-in \var{Time}, and returns them in the \var{Hour}, \var{Minute} and
-\var{Second} and \var{MilliSecond} variables.
-\Errors
-None.
-\SeeAlso
-\seef{EncodeTime}, \seep{DecodeDate}.
-\end{procedure}
-
-\FPCexample{ex10}
-
-
-\begin{function}{EncodeDate}
-\Declaration
-Function EncodeDate(Year, Month, Day :word): TDateTime;
-\Description
-\var{EncodeDate} encodes the \var{Year}, \var{Month} and \var{Day} variables to
-a date in \var{TDateTime} format. It does the opposite of the
-\seep{DecodeDate} procedure.
-
-The parameters must lie withing valid ranges (boundaries included):
-\begin{description}
-\item[Year] must be between 1 and 9999.
-\item[Month] must be within the range 1-12.
-\item[Day] msut be between 1 and 31.
-\end{description}
-\Errors
-In case one of the parameters is out of it's valid range, 0 is returned.
-\SeeAlso
-\seef{EncodeTime}, \seep{DecodeDate}.
-\end{function}
-
-\FPCexample{ex11}
-
-
-\begin{function}{EncodeTime}
-\Declaration
-Function EncodeTime(Hour, Minute, Second, MilliSecond:word): TDateTime;
-\Description
-\var{EncodeTime} encodes the \var{Hour}, \var{Minute}, \var{Second},
-\var{MilliSecond} variables to a \var{TDateTime} format result.
-It does the opposite of the \seep{DecodeTime} procedure.
-
-The parameters must have a valid range (boundaries included):
-\begin{description}
-\item[Hour] must be between 0 and 23.
-\item[Minute,second] must both be between 0 and 59.
-\item[Millisecond] must be between 0 and 999.
-\end{description}
-\Errors
-In case one of the parameters is outside of it's valid range, 0 is returned.
-\SeeAlso
-\seef{EncodeDate}, \seep{DecodeTime}.
-\end{function}
-
-\FPCexample{ex12}
-
-
-
-\begin{function}{FileDateToDateTime}
-\Declaration
-Function FileDateToDateTime(Filedate : Longint) : TDateTime;
-\Description
-\var{FileDateToDateTime} converts the date/time encoded in \var{filedate}
-to a \var{TDateTime} encoded form. It can be used to convert date/time values
-returned by the \seef{FileAge} or \seef{FindFirst}/\seef{FindNext}
-functions to \var{TDateTime} form.
-\Errors
-None.
-\SeeAlso
-\seef{DateTimeToFileDate}
-\end{function}
-
-\FPCexample{ex13}
-
-
-\begin{function}{FormatDateTime}
-\Declaration
-Function FormatDateTime(FormatStr: string; DateTime: TDateTime):string;
-\Description
-\var{FormatDateTime} formats the date and time encoded in \var{DateTime}
-according to the formatting given in \var{FormatStr}. The complete list
-of formatting characters can be found in \sees{formatchars}.
-\Errors
-On error (such as an invalid character in the formatting string), and
-\var{EConvertError} exception is raised.
-\SeeAlso
-\seef{DateTimeToStr}, \seef{DateToStr}, \seef{TimeToStr},
-\seef{StrToDateTime}
-\end{function}
-
-\FPCexample{ex14}
-
-
-
-\begin{function}{IncMonth}
-\Declaration
-Function IncMonth(const DateTime: TDateTime; NumberOfMonths: integer): TDateTime;
-\Description
-\var{IncMonth} increases the month number in \var{DateTime} with
-\var{NumberOfMonths}. It wraps the result as to get a month between 1 and
-12, and updates the year accordingly. \var{NumberOfMonths} can be negative,
-and can be larger than 12 (in absolute value).
-\Errors
-None.
-\SeeAlso
-\seef{Date}, \seef{Time}, \seef{Now}
-\end{function}
-
-
-\FPCexample{ex15}
-
-
-\begin{function}{IsLeapYear}
-\Declaration
-Function IsLeapYear(Year: Word): boolean;
-\Description
-\var{IsLeapYear} returns \var{True} if \var{Year} is a leap year,
-\var{False} otherwise.
-\Errors
-None.
-\SeeAlso
-\seef{IncMonth}, \seef{Date}
-\end{function}
-
-\FPCexample{ex16}
-
-
-\begin{function}{MSecsToTimeStamp}
-\Declaration
-Function MSecsToTimeStamp(MSecs: Comp): TTimeStamp;
-\Description
-\var{MSecsTiTimeStamp} converts the given number of milliseconds to
-a \var{TTimeStamp} date/time notation.
-
-Use \var{TTimeStamp} variables if you need to keep very precise track of
-time.
-\Errors
-None.
-\SeeAlso
-\seef{TimeStampToMSecs}, \seef{DateTimeToTimeStamp},
-\end{function}
-
-\FPCexample{ex17}
-
-
-\begin{function}{Now}
-\Declaration
-Function Now: TDateTime;
-\Description
-\var{Now} returns the current date and time. It is equivalent to
-\var{Date+Time}.
-\Errors
-None.
-\SeeAlso
-\seef{Date}, \seef{Time}
-\end{function}
-
-\FPCexample{ex18}
-
-
-\begin{function}{StrToDate}
-\Declaration
-Function StrToDate(const S: string): TDateTime;
-\Description
-\var{StrToDate} converts the string \var{S} to a \var{TDateTime} date
-value. The Date must consist of 1 to three digits, separated by the
-\var{DateSeparator} character. If two numbers are given, they
-are supposed to form the day and month of the current year. If only
-one number is given, it is supposed to represent the day of the
-current month. (This is \em{not} supported in Delphi)
-
-The order of the digits (y/m/d, m/d/y, d/m/y) is determined from the
-\var{ShortDateFormat} variable.
-\Errors
-On error (e.g. an invalid date or invalid character),
-an \var{EConvertError} exception is raised.
-\SeeAlso
-\seef{StrToTime}, \seef{DateToStr}n \seef{TimeToStr}.
-\end{function}
-
-\FPCexample{ex19}
-
-
-\begin{function}{StrToDateTime}
-\Declaration
-Function StrToDateTime(const S: string): TDateTime;
-\Description
-\var{StrToDateTime} converts the string \var{S} to a \var{TDateTime} date
-and time value. The Date must consist of 1 to three digits, separated by the
-\var{DateSeparator} character. If two numbers are given, they
-are supposed to form the day and month of the current year. If only
-one number is given, it is supposed to represent the day of the
-current month. (This is \em{not} supported in Delphi)
-
-The order of the digits (y/m/d, m/d/y, d/m/y) is determined from the
-\var{ShortDateFormat} variable.
-\Errors
-On error (e.g. an invalid date or invalid character),
-an \var{EConvertError} exception is raised.
-\SeeAlso
-\seef{StrToDate}, \seef{StrToTime}, \seef{DateTimeToStr}
-\end{function}
-
-\FPCexample{ex20}
-
-
-\begin{function}{StrToTime}
-\Declaration
-Function StrToTime(const S: string): TDateTime;
-\Description
-\var{StrToTime} converts the string \var{S} to a \var{TDateTime} time
-value. The time must consist of 1 to 4 digits, separated by the
-\var{TimeSeparator} character. If two numbers are given, they
-are supposed to form the hour and minutes.
-\Errors
-On error (e.g. an invalid date or invalid character),
-an \var{EConvertError} exception is raised.
-\SeeAlso
-\seef{StrToDate}, \seef{StrToDateTime}, \seef{TimeToStr}
-\end{function}
-
-\FPCexample{ex21}
-
-
-\begin{function}{SystemTimeToDateTime}
-\Declaration
-Function SystemTimeToDateTime(const SystemTime: TSystemTime): TDateTime;
-\Description
-\var{SystemTimeToDateTime} converts a \var{TSystemTime} record to a
-\var{TDateTime} style date/time indication.
-\Errors
-None.
-\SeeAlso
-\seep{DateTimeToSystemTime}
-\end{function}
-
-\FPCexample{ex22}
-
-
-\begin{function}{Time}
-\Declaration
-Function Time: TDateTime;
-\Description
-\var{Time} returns the current time in \var{TDateTime} format. The date
-part of the \var{TDateTimeValue} is set to zero.
-\Errors
-None.
-\SeeAlso
-\seef{Now}, \seef{Date}
-\end{function}
-
-
-\FPCexample{ex23}
-
-
-\begin{function}{TimeStampToDateTime}
-\Declaration
-Function TimeStampToDateTime(const TimeStamp: TTimeStamp): TDateTime;
-\Description
-\var{TimeStampToDateTime} converts \var{TimeStamp} to a \var{TDateTime}
-format variable. It is the inverse operation of \seef{DateTimeToTimeStamp}.
-\Errors
-None.
-\SeeAlso
-\seef{DateTimeToTimeStamp}, \seef{TimeStampToMSecs}
-\end{function}
-
-\FPCexample{ex24}
-
-
-\begin{function}{TimeStampToMSecs}
-\Declaration
-Function TimeStampToMSecs(const TimeStamp: TTimeStamp): comp;
-\Description
-\var{TimeStampToMSecs} converts {TimeStamp} to the number of seconds
-since \var{1/1/0001}.
-
-Use \var{TTimeStamp} variables if you need to keep very precise track of
-time.
-\Errors
-None.
-\SeeAlso
-\seef{MSecsToTimeStamp}, \seef{TimeStampToDateTime}
-\end{function}
-
-For an example, see \seef{MSecsToTimeStamp}.
-
-\begin{function}{TimeToStr}
-\Declaration
-Function TimeToStr(Time: TDateTime): string;
-\Description
-\var{TimeToStr} converts the time in \var{Time} to a string. It uses
-the \var{ShortTimeFormat} variable to see what formatting needs to be
-applied. It is therefor entirely equivalent to a
-\var{FormatDateTime('t',Time)} call.
-\Errors
-None.
-\SeeAlso
-\end{function}
-
-\FPCexample{ex25}
-
-
-
-\section{Disk functions}
-
-\begin{functionl}{AddDisk (Linux only)}{AddDisk}
-\Declaration
-Function AddDisk (Const PAth : String) : Longint;
-\Description
-On Linux  both the \seef{DiskFree} and \seef{DiskSize} functions need a
-file on the specified drive, since is required for the statfs system call.
-
-These filenames are set in drivestr[0..26], and the first 4 have been
-preset to :
-\begin{description}
-\item[Disk 0]  \var{'.'} default drive - hence current directory is used.
-\item[Disk 1]  \var{'/fd0/.'} floppy drive 1.
-\item[Disk 2]  \var{'/fd1/.'} floppy drive 2.
-\item[Disk 3]  \var{'/'} \file{C:} equivalent of DOS is the root partition.
-\end{description}
-Drives 4..26 can be set by your own applications with the \var{AddDisk} call.
-
-The \var{AddDisk} call adds \var{Path} to the names of drive files, and
-returns the number of the disk that corresponds to this drive. If you
-add more than 21 drives, the count is wrapped to 4.
-\Errors
-None.
-\SeeAlso
-\seefl{DiskFree}{DiskFreeSys}, \seefl{DiskSize}{DiskSizeSys}
-\end{functionl}
-
-\begin{function}{CreateDir}
-\Declaration
-Function CreateDir(Const NewDir : String) : Boolean;
-\Description
-\var{CreateDir} creates a new directory with name \var{NewDir}.
-If the directory doesn't contain an absolute path, then the directory is
-created below the current working directory.
-
-The function returns \var{True} if the directory was successfully
-created, \var{False} otherwise.
-\Errors
-In case of an error, the function returns \var{False}.
-\SeeAlso
-\seef{RemoveDir}
-\end{function}
-
-\FPCexample{ex26}
-
-
-\begin{functionl}{DiskFree}{DiskFreeSys}
-\Declaration
-Function DiskFree(Drive : Byte) : Int64;
-\Description
-\var{DiskFree} returns the free space (in bytes) on disk \var{Drive}.
-Drive is the number of the disk drive:
-\begin{description}
-\item[0] for the current drive.
-\item[1] for the first floppy drive.
-\item[2] for the second floppy drive.
-\item[3] for the first hard-disk parttion.
-\item[4-26] for all other drives and partitions.
-\end{description}
-
-{\em Remark} Under \linux, and Unix in general, the concept of disk is
-different than the \dos one, since the filesystem is seen as one big
-directory tree. For this reason, the \var{DiskFree} and \seef{DiskSize}
-functions must be mimicked using filenames that reside on the partitions.
-For more information, see \seef{AddDisk}
-\Errors
-On error, \var{-1} is returned.
-\SeeAlso
-\seefl{DiskSize}{DiskSizeSys}, \seef{AddDisk}
-\end{functionl}
-
-\FPCexample{ex27}
-
-
-\begin{functionl}{DiskSize}{DiskSizeSys}
-\Declaration
-Function DiskSize(Drive : Byte) : Int64;
-\Description
-\var{DiskSize} returns the size (in bytes) of disk \var{Drive}.
-Drive is the number of the disk drive:
-\begin{description}
-\item[0] for the current drive.
-\item[1] for the first floppy drive.
-\item[2] for the second floppy drive.
-\item[3] for the first hard-disk parttion.
-\item[4-26] for all other drives and partitions.
-\end{description}
-
-{\em Remark} Under \linux, and Unix in general, the concept of disk is
-different than the \dos one, since the filesystem is seen as one big
-directory tree. For this reason, the \seef{DiskFree} and \var{DiskSize}
-functions must be mimicked using filenames that reside on the partitions.
-For more information, see \seef{AddDisk}
-\Errors
-On error, \var{-1} is returned.
-\SeeAlso
-\seefl{DiskFree}{DiskFreeSys}, \seef{AddDisk}
-\end{functionl}
-
-For an example, see \seefl{DiskFree}{DiskFreeSys}.
-
-\begin{function}{GetCurrentDir}
-\Declaration
-Function GetCurrentDir : String;
-\Description
-\var{GetCurrentDir} returns the current working directory.
-\Errors
-None.
-\SeeAlso
-\seef{SetCurrentDir}, \seef{DiskFree}, \seef{DiskSize}
-\end{function}
-
-\FPCexample{ex28}
-
-
-\begin{function}{RemoveDir}
-\Declaration
-Function RemoveDir(Const Dir : String) : Boolean;
-\Description
-\var{RemoveDir} removes directory \var{Dir} from the disk.
-If the directory is not absolue, it is appended to the current working
-directory.
-\Errors
-In case of error (e.g. the directory isn't empty) the function returns
-\var{False}. If successful, \var{True} is returned.
-\SeeAlso
-\end{function}
-
-For an example, see \seef{CreateDir}.
-
-\begin{function}{SetCurrentDir}
-\Declaration
-Function SetCurrentDir(Const NewDir : String) : Boolean;
-\Description
-\var{SetCurrentDir} sets the current working directory of your program
-to \var{NewDir}. It returns \var{True} if the function was successfull,
-\var{False} otherwise.
-\Errors
-In case of error, \var{False} is returned.
-\SeeAlso
-\seef{GetCurrentDir}
-\end{function}
-
-\FPCexample{ex29}
-
-
-\section{File handling functions}
-
-\begin{function}{ChangeFileExt}
-\Declaration
-Function ChangeFileExt(const FileName, Extension: string): string;
-\Description
-\var{ChangeFileExt} changes the file extension in \var{FileName} to
-\var{Extension}.
-The extension \var{Extension} includes the starting \var{.} (dot).
-The previous extension of \var{FileName} are all characters after the
-last \var{.}, the \var{.} character included.
-
-If \var{FileName} doesn't have an extension, \var{Extension} is just
-appended.
-\Errors
-None.
-\SeeAlso
-\seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExpandFileName}
-\end{function}
-
-
-\begin{function}{DeleteFile}
-\Declaration
-Function DeleteFile(Const FileName : String) : Boolean;
-\Description
-\var{DeleteFile} deletes file \var{FileName} from disk. The function
-returns \var{True} if the file was successfully removed, \var{False}
-otherwise.
-\Errors
-On error, \var{False} is returned.
-\SeeAlso
-\seef{FileCreate}, \seef{FileExists}
-\end{function}
-
-\FPCexample{ex31}
-
-
-\begin{procedure}{DoDirSeparators}
-\Declaration
-Procedure DoDirSeparators(Var FileName : String);
-\Description
-This function replaces all directory separators \var{'\\' and '/'}
-to the directory separator character for the current system.
-\Errors
-None.
-\SeeAlso
-\seef{ExtractFileName}, \seef{ExtractFilePath}
-\end{procedure}
-
-\FPCexample{ex32}
-
-
-\begin{function}{ExpandFileName}
-\Declaration
-Function ExpandFileName(Const FileName : string): String;
-\Description
-\var{ExpandFileName} expands the filename to an absolute filename.
-It changes all directory separator characters to the one appropriate for the
-system first.
-\Errors
-None.
-\SeeAlso
-\seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir},
-\seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath}
-\end{function}
-
-\FPCexample{ex33}
-
-
-
-\begin{function}{ExpandUNCFileName}
-\Declaration
-Function ExpandUNCFileName(Const FileName : string): String;
-\Description
-\var{ExpandUNCFileName} runs \seef{ExpandFileName} on \var{FileName}
-and then attempts to replace the driveletter by the name of a shared disk.
-\Errors
-None.
-\SeeAlso
-\seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir},
-\seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath}
-\end{function}
-
-
-\begin{function}{ExtractFileDir}
-\Declaration
-Function ExtractFileDir(Const FileName : string): string;
-\Description
-\var{ExtractFileDir} returns only the directory part of \var{FileName},
-not including a driveletter. The directory name has NO ending directory
-separator, in difference with \seef{ExtractFilePath}.
-\Errors
-None.
-\SeeAlso
-\seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir},
-\seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath}
-\end{function}
-
-\FPCexample{ex34}
-
-
-\begin{function}{ExtractFileDrive}
-\Declaration
-Function ExtractFileDrive(const FileName: string): string;
-\Description
-\var{Extract}
-\Errors
-\SeeAlso
-\seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir},
-\seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath}
-\end{function}
-
-For an example, see \seef{ExtractFileDir}.
-
-\begin{function}{ExtractFileExt}
-\Declaration
-Function ExtractFileExt(const FileName: string): string;
-\Description
-\var{ExtractFileExt} returns the extension (including the
-\var{.}(dot) character) of \var{FileName}.
-\Errors
-None.
-\SeeAlso
-\seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir},
-\seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath}
-\end{function}
-
-For an example, see \seef{ExtractFileDir}.
-
-\begin{function}{ExtractFileName}
-\Declaration
-Function ExtractFileName(const FileName: string): string;
-\Description
-\var{ExtractFileName} returns the filename part from \var{FileName}.
-The filename consists of all characters after the last directory separator
-character ('/' or '\') or drive letter.
-
-The full filename can always be reconstucted by concatenating the result
-of \seef{ExtractFilePath} and \var{ExtractFileName}.
-\Errors
-None.
-\SeeAlso
-\seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir},
-\seef{ExtractFileDrive}, \seef{ExtractFileExt},\seef{ExtractRelativePath}
-\end{function}
-
-For an example, see \seef{ExtractFileDir}.
-
-\begin{function}{ExtractFilePath}
-\Declaration
-Function ExtractFilePath(const FileName: string): string;
-\Description
-\var{ExtractFilePath} returns the path part (including driveletter) from
-\var{FileName}. The path consists of all characters before the last
-directory separator character ('/' or '\'), including the directory
-separator itself.
-In case there is only a drive letter, that will be returned.
-
-The full filename can always be reconstucted by concatenating the result
-of \var{ExtractFilePath} and \seef{ExtractFileName}.
-\Errors
-None.
-\SeeAlso
-\seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir},
-\seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath}
-\end{function}
-
-For an example, see \seef{ExtractFileDir}.
-
-\begin{function}{ExtractRelativePath}
-\Declaration
-Function ExtractRelativePath(Const BaseName,DestNAme : String): String;
-\Description
-\var{ExtractRelativePath} constructs a relative path to go from
-\var{BaseName} to \var{DestName}. If \var{DestName} is on another drive
-(Not on Linux) then the whole \var{Destname} is returned.
-
-{\em Note:} This function does not exist in the Delphi unit.
-\Errors
-None.
-\SeeAlso
-\seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir},
-\seef{ExtractFileDrive}, \seef{ExtractFileExt},
-\end{function}
-
-\FPCexample{ex35}
-
-
-\begin{function}{FileAge}
-\Declaration
-Function FileAge(Const FileName : String): Longint;
-\Description
-\var{FileAge} returns the last modification time of file \var{FileName}.
-The FileDate format can be transformed to \var{TDateTime} format with the
-\seef{FileDateToDateTime} function.
-\Errors
-In case of errors, \var{-1} is returned.
-\SeeAlso
-\seef{FileDateToDateTime}, \seef{FileExists}, \seef{FileGetAttr}
-\end{function}
-
-\FPCexample{ex36}
-
-
-
-\begin{procedure}{FileClose}
-\Declaration
-Procedure FileClose(Handle : Longint);
-\Description
-\var{FileClose} closes the file handle \var{Handle}. After this call,
-attempting to read or write from the handle will result in an error.
-\Errors
-None.
-\SeeAlso
-\seef{FileCreate}, \seef{FileWrite}, \seef{FileOpen}, \seef{FileRead},
-\seef{FileTruncate}, \seef{FileSeek}
-\end{procedure}
-
-For an example, see \seef{FileCreate}
-
-\begin{function}{FileCreate}
-\Declaration
-Function FileCreate(Const FileName : String) : Longint;
-\Description
-\var{FileCreate} creates a new file with name \var{FileName} on the disk and
-returns a file handle which can be used to read or write from the file with
-the \seef{FileRead} and \seef{FileWrite} functions.
-
-If a file with name \var{FileName} already existed on the disk, it is
-overwritten.
-\Errors
-If an error occurs (e.g. disk full or non-existent path), the function
-returns \var{-1}.
-\SeeAlso
-\seep{FileClose}, \seef{FileWrite}, \seef{FileOpen}, \seef{FileRead},
-\seef{FileTruncate}, \seef{FileSeek}
-\end{function}
-
-\FPCexample{ex37}
-
-
-\begin{function}{FileExists}
-\Declaration
-Function FileExists(Const FileName : String) : Boolean;
-\Description
-\var{FileExists} returns \var{True} if a file with name \var{FileName}
-exists on the disk, \var{False} otherwise.
-\Errors
-None.
-\SeeAlso
-\seef{FileAge}, \seef{FileGetAttr}, \seef{FileSetAttr}
-\end{function}
-
-
-\FPCexample{ex38}
-
-
-
-\begin{function}{FileGetAttr}
-\Declaration
-Function FileGetAttr(Const FileName : String) : Longint;
-\Description
-\var{FileGetAttr} returns the attribute settings of file
-\var{FileName}. The attribute is a \var{OR}-ed combination
-of the following constants:
-\begin{description}
-\item[faReadOnly] The file is read-only.
-\item[faHidden] The file is hidden. (On \linux, this means that the filename
-starts with a dot)
-\item[faSysFile] The file is a system file (On \linux, this means that the
-file is a character, block or FIFO file).
-\item[faVolumeId] Volume Label. Not possible under \linux.
-\item[faDirectory] File is a directory.
-\item[faArchive] file is an archive. Not possible on \linux.
-\end{description}
-\Errors
-In case of error, -1 is returned.
-\SeeAlso
-\seef{FileSetAttr}, \seef{FileAge}, \seef{FileGetDate}.
-\end{function}
-
-\FPCexample{ex40}
-
-
-\begin{function}{FileGetDate}
-\Declaration
-Function FileGetDate(Handle : Longint) : Longint;
-\Description
-\var{FileGetdate} returns the filetime of the opened file with filehandle
-\var{Handle}. It is the same as \seef{FileAge}, with this difference that
-\var{FileAge} only needs the file name, while \var{FilegetDate} needs an
-open file handle.
-\Errors
-On error, -1 is returned.
-\SeeAlso
-\seef{FileAge}
-\end{function}
-
-\FPCexample{ex39}
-
-
-\begin{function}{FileOpen}
-\Declaration
-Function FileOpen(Const FileName : string; Mode : Integer) : Longint;
-\Description
-\var{FileOpen} opens a file with name \var{FileName} with mode \var{Mode}.
-\var{Mode} can be one of the following constants:
-\begin{description}
-\item[fmOpenRead] The file is opened for reading.
-\item[fmOpenWrite] The file is opened for writing.
-\item[fmOpenReadWrite] The file is opened for reading and writing.
-\end{description}
-If the file has been successfully opened, it can be read  from or written to
-(depending on the \var{Mode} parameter) with the \seef{FileRead} and
-\var{FileWrite} functions.
-
-Remark that you cannot open a file if it doesn't exist yet, i.e. it will not
-be created for you. If you want tp create a new file, or overwrite an old
-one, use the \seef{FileCreate} function.
-\Errors
-On Error, -1 is returned.
-\SeeAlso
-\seep{FileClose}, \seef{FileWrite}, \seef{FileCreate}, \seef{FileRead},
-\seef{FileTruncate}, \seef{FileSeek}
-\end{function}
-
-For an example, see \seef{FileOpen}
-
-\begin{function}{FileRead}
-\Declaration
-Function FileRead(Handle : Longint; Var Buffer; Count : longint) : Longint;
-\Description
-\var{FileRead} reads \var{Count} bytes from file-handle \var{Handle} and
-stores them into \var{Buffer}. Buffer must be at least \var{Count} bytes
-long. No checking on this is performed, so be careful not to overwrite any
-memory.  \var{Handle} must be the result of a \seef{FileOpen} call.
-\Errors
-On error, -1 is returned.
-\SeeAlso
-\seep{FileClose}, \seef{FileWrite}, \seef{FileCreate}, \seef{FileOpen},
-\seef{FileTruncate}, \seef{FileSeek}
-\end{function}
-
-For an example, see \seef{FileCreate}
-
-\begin{function}{FileSearch}
-\Declaration
-Function FileSearch(Const Name, DirList : String) : String;
-\Description
-\var{FileSearch} looks for the file \var{Name} in \var{DirList}, where
-dirlist is a list of directories, separated by semicolons or colons.
-It returns the full filename of the first match found.
-\Errors
-On error, an empty string is returned.
-\SeeAlso
-\seef{ExpandFileName}, \seef{FindFirst}
-\end{function}
-
-\FPCexample{ex41}
-
-
-\begin{function}{FileSeek}
-\Declaration
-Function FileSeek(Handle,Offset,Origin : Longint) : Longint;
-\Description
-\var{FileSeek} sets the file pointer on position \var{Offset}, starting from
-\var{Origin}. Origin can be one of the following values:
-\begin{description}
-\item[fsFromBeginning]  \var{Offset} is relative to the first byte of the file. This
-position is zero-based. i.e. the first byte is at offset 0.
-\item[fsFromCurrent]  \var{Offset} is relative to the current position.
-\item[fsFromEnd] \var{Offset} is relative to the end of the file. This means
-that \var{Offset} can only be zero or negative in this case.
-\end{description}
-If successfull, the function returns the new file position, relative to the
-beginning of the file.
-
-{\em Remark:} The abovementioned constants do not exist in Delphi.
-\Errors
-On error, -1 is returned.
-\SeeAlso
-\seep{FileClose}, \seef{FileWrite}, \seef{FileCreate}, \seef{FileOpen}
-\seef{FileRead}, \seef{FileTruncate}
-\end{function}
-
-\FPCexample{ex42}
-
-
-For an example, see \seef{FileCreate}
-
-\begin{functionl}{FileSetAttr (Not on Linux)}{FileSetAttr}
-\Declaration
-Function FileSetAttr(Const Filename : String; Attr: longint) : Longint;
-\Description
-\var{FileSetAttr} sets the attributes of \var{FileName} to \var{Attr}.
-If the function was successful, 0 is returned, -1 otherwise.
-
-\var{Attr} can be set to an OR-ed combination of the pre-defined
-\var{faXXX} constants.
-\Errors
-On error, -1 is returned (always on linux).
-\SeeAlso
-\seef{FileGetAttr}, \seef{FileGetDate}, \seef{FileSetDate}.
-\end{functionl}
-
-
-\begin{functionl}{FileSetDate (Not on Linux)}{FileSetDate}
-\Declaration
-Function FileSetDate(Handle,Age : Longint) : Longint;
-\Description
-\var{FileSetDate} sets the file date of the file with handle \var{Handle}
-to \var{Age}, where \var{Age} is a DOS date-and-time stamp value.
-
-The function returns zero of successfull.
-\Errors
-On Linux, -1 is always returned, since this is impossible to implement.
-On Windows and DOS, a negative error code is returned.
-\SeeAlso
-\end{functionl}
-
-
-\begin{function}{FileTruncate}
-\Declaration
-Function FileTruncate(Handle,Size: Longint) : boolean;
-\Description
-\var{FileTruncate} truncates the file with handle \var{Handle} to
-\var{Size} bytes. The file must have been opened for writing prior
-to this call. The function returns \var{True} is successful, \var{False}
-otherwise.
-\Errors
-On error, the function returns \var{False}.
-\SeeAlso
-\seep{FileClose}, \seef{FileWrite}, \seef{FileCreate}, \seef{FileOpen}
-\seef{FileRead}, \seef{FileSeek}
-\end{function}
-
-For an example, see \seef{FileCreate}.
-
-\begin{function}{FileWrite}
-\Declaration
-Function FileWrite(Handle : Longint; Var Buffer; Count : Longint) : Longint;
-\Description
-\var{FileWrite} writes \var{Count} bytes from \var{Buffer} to the file with
-handle \var{Handle}. Prior to this call, the file must have been opened
-for writing. \var{Buffer} must be at least \var{Count} bytes large, or
-a memory access error may occur.
-
-The function returns the number of bytes written, or -1 in case of an
-error.
-\Errors
-In case of error, -1 is returned.
-\SeeAlso
-\seep{FileClose}, \seef{FileCreate}, \seef{FileOpen}
-\seef{FileRead}, \seef{FileTruncate}, \seef{FileSeek}
-\end{function}
-
-For an example, see \seef{FileCreate}.
-
-\begin{procedurel}{FindClose}{FindCloseSys}
-\Declaration
-Procedure FindClose(Var F : TSearchrec);
-\Description
-\var{FindClose} ends a series of \seef{FindFirst}/\seef{FindNext} calls,
-and frees any memory used by these calls. It is {\em absolutely} necessary
-to do this call, or huge memory losses may occur.
-\Errors
-None.
-\SeeAlso
-\seef{FindFirst}, \seef{FindNext}.
-\end{procedurel}
-
-For an example, see \seef{FindFirst}.
-
-\begin{function}{FindFirst}
-\Declaration
-Function FindFirst(Const Path : String; Attr : Longint; Var Rslt : TSearchRec) : Longint;
-\Description
-\var{FindFirst} looks for files that match the name (possibly with
-wildcards) in \var{Path} and attributes \var{Attr}. It then fills up the
-\var{Rslt} record with data gathered about the file. It returns 0 if a file
-matching the specified criteria is found, a nonzero value (-1 on linux)
-otherwise.
-
-The \var{Rslt} record can be fed to subsequent calls to \var{FindNext}, in
-order to find other files matching the specifications.
-
-{\em remark:} A \var{FindFirst} call must {\em always} be followed by a
-\seepl{FindClose}{FindCloseSys} call with the same \var{Rslt} record. Failure to do so will
-result in memory loss.
-\Errors
-On error the function returns -1 on linux, a nonzero error code on Windows.
-\SeeAlso
-\seep{FindClose}{FindCloseSys}, \seef{FindNext}.
-\end{function}
-
-\FPCexample{ex43}
-
-
-\begin{function}{FindNext}
-\Declaration
-Function FindNext(Var Rslt : TSearchRec) : Longint;
-\Description
-\var{FindNext} finds a next occurrence of a search sequence initiated by
-\var{FindFirst}. If another record matching the criteria in Rslt is found, 0
-is returned, a nonzero constant is returned otherwise.
-
-{\em remark:} The last \var{FindNext} call must {\em always} be followed by a
-\var{FindClose} call with the same \var{Rslt} record. Failure to do so will
-result in memory loss.
-\Errors
-On error (no more file is found), a nonzero constant is returned.
-\SeeAlso
-\seef{FindFirst}, \seep{FindClose}
-\end{function}
-
-For an example, see \seef{FindFirst}
-
-\begin{function}{GetDirs}
-\Declaration
-Function GetDirs(Var DirName : String; Var Dirs : Array of pchar) : Longint;
-\Description
-\var{GetDirs} splits DirName in a null-byte separated list of directory names,
-\var{Dirs} is an array of \var{PChars}, pointing to these directory names.
-The function returns the number of directories found, or -1 if none were found.
-DirName must contain only OSDirSeparator as Directory separator chars.
-\Errors
-None.
-\SeeAlso
-\seef{ExtractRelativePath}
-\end{function}
-
-\FPCexample{ex45}
-
-
-\begin{function}{RenameFile}
-\Declaration
-Function RenameFile(Const OldName, NewName : String) : Boolean;
-\Description
-\var{RenameFile} renames a file from \var{OldName} to \var{NewName}. The
-function returns \var{True} if successful, \var{False} otherwise.
-
-{\em Remark:} you cannot rename across disks or partitions.
-\Errors
-On Error, \var{False} is returned.
-\SeeAlso
-\seef{DeleteFile}
-\end{function}
-
-\FPCexample{ex44}
-
-
-\begin{function}{SetDirSeparators}
-\Declaration
-Function SetDirSeparators(Const FileName : String) : String;
-\Description
-\var{SetDirSeparators} returns \var{FileName} with all possible
-DirSeparators replaced by \var{OSDirSeparator}.
-\Errors
-None.
-\SeeAlso
-\seef{ExpandFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir}
-\end{function}
-
-\FPCexample{ex47}
-
-
-\section{PChar functions}
-
-\subsection{Introduction}
-
-Most PChar functions are the same as their counterparts in the \file{STRINGS}
-unit. The following functions are the same :
-
-\begin{enumerate}
-\item \seef{StrCat} : Concatenates two \var{PChar} strings.
-\item \seef{StrComp} : Compares two \var{PChar} strings.
-\item \seef{StrCopy} : Copies a \var{PChar} string.
-\item \seef{StrECopy} : Copies a \var{PChar} string and returns a pointer to
-the terminating null byte.
-\item \seef{StrEnd} : Returns a pointer to the terminating null byte.
-\item \seef{StrIComp} : Case insensitive compare of 2 \var{PChar} strings.
-\item \seef{StrLCat} : Appends at most L characters from one \var{PChar} to
-another \var{PChar}.
-\item \seef{StrLComp} : Case sensitive compare of at most L characters of 2
- \var{PChar} strings.
-\item \seef{StrLCopy} : Copies at most L characters from one \var{PChar} to
-another.
-\item \seef{StrLen} : Returns the length (exclusive terminating null byte)
-of a \var{PChar} string.
-\item \seef{StrLIComp} : Case insensitive compare of at most L characters of 2
- \var{PChar} strings.
-\item \seef{StrLower} : Converts a \var{PChar} to all lowercase letters.
-\item \seef{StrMove} : Moves one \var{PChar} to another.
-\item \seef{StrNew} : Makes a copy of a \var{PChar} on the heap, and returns
-a pointer to this copy.
-\item \seef{StrPos} : Returns the position of one \var{PChar} string in
-another?
-\item \seef{StrRScan} : returns a pointer to the last occurrence of on
- \var{PChar} string in another one.
-\item \seef{StrScan} : returns a pointer to the first occurrence of on
- \var{PChar} string in another one.
-\item \seef{StrUpper} : Converts a \var{PChar} to all uppercase letters.
-\end{enumerate}
-The subsequent functions are different from their counterparts in
-\file{STRINGS}, although the same examples can be used.
-
-
-\begin{functionl}{StrAlloc}{StrAllocSys}
-\Declaration
-Function StrAlloc(Size: cardinal): PChar;
-\Description
-\var{StrAlloc} reserves memory on the heap for a string with length \var{Len},
-terminating \var{\#0} included, and returns a pointer to it.
-
-Additionally, \var{StrAlloc} allocates 4 extra bytes to store the size of
-the allocated memory. Therefore this function is NOT compatible with the
-\seef{StrAlloc} function of the \var{Strings} unit.
-\Errors
-None.
-\SeeAlso
-\seef{StrBufSize}, \seepl{StrDispose}{StrDisposeSys}, \seef{StrAlloc}
-\end{functionl}
-
-For an example, see \seef{StrBufSize}.
-
-\begin{function}{StrBufSize}
-\Declaration
-Function StrBufSize(var Str: PChar): cardinal;
-\Description
-\var{StrBufSize} returns the memory allocated for \var{Str}. This function
-ONLY gives the correct result if \var{Str} was allocated using
-\seefl{StrAlloc}{StrAllocSys}.
-\Errors
-If no more memory is available, a runtime error occurs.
-\SeeAlso
-\seefl{StrAlloc}{StrAllocSys}.\seepl{StrDispose}{StrDisposeSys}.
-\end{function}
-
-\FPCexample{ex46}
-
-
-
-\begin{procedurel}{StrDispose}{StrDisposeSys}
-\Declaration
-Procedure StrDispose(var Str: PChar);
-\Description
-\var{StrDispose} frees any memory allocated for \var{Str}. This function
-will only function correctly if \var{Str} has been allocated using
-\seefl{StrAlloc}{StrAllocSys} from the \file{SYSUTILS} unit.
-\Errors
-If an invalid pointer is passed, or a pointer not allocated with
-\var{StrAlloc}, an error may occur.
-\SeeAlso
-\seef{StrBufSize}, \seefl{StrAlloc}{StrAllocSys}, \seep{StrDispose}
-\end{procedurel}
-
-For an example, see \seef{StrBufSize}.
-
-\begin{functionl}{StrPCopy}{StrPCopySys}
-\Declaration
-Function StrPCopy(Dest: PChar; Source: string): PChar;
-\Description
-\var{StrPCopy} Converts the Ansistring in \var{Source} to a Null-terminated
-string, and copies it to \var{Dest}. \var{Dest} needs enough room to contain
-the string \var{Source}, i.e. \var{Length(Source)+1} bytes.
-\Errors
-No checking is performed to see whether \var{Dest} points to enough memory
-to contain \var{Source}.
-\SeeAlso
-\seefl{StrPLCopy}{StrPLCopySys}, \seef{StrPCopy}
-\end{functionl}
-
-For an example, see \seef{StrPCopy}.
-
-\begin{functionl}{StrPLCopy}{StrPLCopySys}
-\Declaration
-Function StrPLCopy(Dest: PChar; Source: string; MaxLen: cardinal): PChar;
-\Description
-\var{StrPLCopy} Converts maximally \var{MaxLen} characters of the
-Ansistring in \var{Source} to a Null-terminated  string, and copies
-it to \var{Dest}. \var{Dest} needs enough room to contain
-the  characters.
-\Errors
-No checking is performed to see whether \var{Dest} points to enough memory
-to contain L characters of \var{Source}.
-\Errors
-\SeeAlso
-\seefl{StrPCopy}{StrPCopySys}.
-\end{functionl}
-
-
-\begin{functionl}{StrPas}{StrPasSys}
-\Declaration
-Function StrPas(Str: PChar): string;
-\Description
-Converts a null terminated string in \var{Str} to an Ansitring, and returns
-this string. This string is NOT truncated at 255 characters as is the
-\Errors
-None.
-\SeeAlso
-\seef{StrPas}.
-\end{functionl}
-
-For an example, see \seef{StrPas}.
-
-\section{String handling functions}
-
-\begin{function}{AdjustLineBreaks}
-\Declaration
-Function AdjustLineBreaks(const S: string): string;
-\Description
-\var{AdjustLineBreaks} will change all \var{\#13} characters with
-\var{\#13\#10} on \windowsnt and \dos. On \linux, all \var{\#13\#10}
-character pairs are converted to \var{\#10} and single \var{\#13}
-characters also.
-\Errors
-None.
-\SeeAlso
-\seef{AnsiCompareStr}, \seef{AnsiCompareText}
-\end{function}
-
-\FPCexample{ex48}
-
-
-\begin{function}{AnsiCompareStr}
-\Declaration
-Function AnsiCompareStr(const S1, S2: string): integer;
-\Description
-\var{AnsiCompareStr} compares two strings and returns the following
-result:
-\begin{description}
-\item[<0]  if \var{S1<S2}.
-\item[0]  if \var{S1=S2}.
-\item[>0] if \var{S1>S2}.
-\end{description}
-the comparision takes into account Ansi characters, i.e. it takes
-care of strange accented characters. Contrary to \seef{AnsiCompareText},
-the comparision is case sensitive.
-\Errors
-None.
-\SeeAlso
-\seef{AdjustLineBreaks}, \seef{AnsiCompareText}
-\end{function}
-
-\FPCexample{ex49}
-
-
-\begin{function}{AnsiCompareText}
-\Declaration
-Function AnsiCompareText(const S1, S2: string): integer;
-\Description
-\Description
-\var{AnsiCompareText} compares two strings and returns the following
-result:
-\begin{description}
-\item[<0]  if \var{S1<S2}.
-\item[0]  if \var{S1=S2}.
-\item[>0] if \var{S1>S2}.
-\end{description}
-the comparision takes into account Ansi characters, i.e. it takes
-care of strange accented characters. Contrary to \seef{AnsiCompareStr},
-the comparision is case insensitive.
-\Errors
-None.
-\SeeAlso
-\seef{AdjustLineBreaks}, \seef{AnsiCompareText}
-\end{function}
-
-\FPCexample{ex50}
-
-
-\begin{function}{AnsiExtractQuotedStr}
-\Declaration
-Function AnsiExtractQuotedStr(var Src: PChar; Quote: Char): string;
-\Description
-\var{AnsiExtractQuotedStr} Returns \var{Src} as a string, with \var{Quote}
-characters removed from the beginning and end of the string, and double
-\var{Quote} characters replaced by a single \var{Quote} characters.
-As such, it revereses the action of \seef{AnsiQuotedStr}.
-\Errors
-None.
-\SeeAlso
-\seef{AnsiQuotedStr}
-\end{function}
-
-\FPCexample{ex51}
-
-
-\begin{function}{AnsiLastChar}
-\Declaration
-Function AnsiLastChar(const S: string): PChar;
-\Description
-This function returns a pointer to the last character of \var{S}.
-Since multibyte characters are not yet supported, this is the same
-as \var{@S[Length(S)])}.
-\Errors
-None.
-\SeeAlso
-\seef{AnsiStrLastChar}
-\end{function}
-
-\FPCexample{ex52}
-
-
-\begin{function}{AnsiLowerCase}
-\Declaration
-Function AnsiLowerCase(const s: string): string;
-\Description
-\var{AnsiLowerCase} converts the string \var{S} to lowercase characters
-and returns the resulting string.
-It takes into account the operating system language
-settings when doing this, so spcial characters are converted correctly as
-well.
-
-{\em Remark} On linux, no language setting is taken in account yet.
-\Errors
-None.
-\SeeAlso
-\seef{AnsiUpperCase}, \seef{AnsiStrLower}, \seef{AnsiStrUpper}
-\end{function}
-
-\FPCexample{ex53}
-
-
-\begin{function}{AnsiQuotedStr}
-\Declaration
-Function AnsiQuotedStr(const S: string; Quote: char): string;
-\Description
-\var{AnsiQuotedString} quotes the string \var{S} and returns the result.
-This means that it puts the \var{Quote} character at both the beginning and
-end of the string and replaces any occurrence of \var{Quote} in \var{S}
-with 2 \var{Quote} characters. The action of \var{AnsiQuotedString} can be
-reversed by \seef{AnsiExtractQuotedStr}.
-\Errors
-None.
-\SeeAlso
-\seef{AnsiExtractQuotedStr}
-\end{function}
-
-For an example, see \seef{AnsiExtractQuotedStr}
-
-\begin{function}{AnsiStrComp}
-\Declaration
-Function AnsiStrComp(S1, S2: PChar): integer;
-\Description
-\var{AnsiStrComp} compares 2 \var{PChar} strings, and returns the following
-result:
-\begin{description}
-\item[<0]  if \var{S1<S2}.
-\item[0]  if \var{S1=S2}.
-\item[>0]  if \var{S1>S2}.
-\end{description}
-The comparision of the two strings is case-sensitive.
-The function does not yet take internationalization settings into account.
-\Errors
-None.
-\SeeAlso
-\seef{AnsiCompareText}, \seef{AnsiCompareStr}
-\end{function}
-
-\FPCexample{ex54}
-
-
-\begin{function}{AnsiStrIComp}
-\Declaration
-Function AnsiStrIComp(S1, S2: PChar): integer;
-\Description
-\var{AnsiStrIComp} compares 2 \var{PChar} strings, and returns the following
-result:
-\begin{description}
-\item[<0]  if \var{S1<S2}.
-\item[0]  if \var{S1=S2}.
-\item[>0]  if \var{S1>S2}.
-\end{description}
-The comparision of the two strings is case-insensitive.
-The function does not yet take internationalization settings into account.
-\Errors
-None.
-\SeeAlso
-\seef{AnsiCompareText}, \seef{AnsiCompareStr}
-\end{function}
-
-\FPCexample{ex55}
-
-
-\begin{function}{AnsiStrLastChar}
-\Declaration
-function AnsiStrLastChar(Str: PChar): PChar;
-\Declaration
-\var{AnsiStrLastChar} returns a pointer to the last character of \var{Str}.
-Since multibyte characters are not yet supported, this is the same
-as \var{StrEnd(Str)-1}.
-\Errors
-None.
-\SeeAlso
-\seef{AnsiLastChar}
-\end{function}
-
-\FPCexample{ex58}
-
-
-\begin{function}{AnsiStrLComp}
-\Declaration
-Function AnsiStrLComp(S1, S2: PChar; MaxLen: cardinal): integer;
-\Description
-\var{AnsiStrLComp} compares the first \var{Maxlen} characters of
-2 \var{PChar} strings, \var{S1} and \var{S2}, and returns the following
-result:
-\begin{description}
-\item[<0]  if \var{S1<S2}.
-\item[0]  if \var{S1=S2}.
-\item[>0]  if \var{S1>S2}.
-\end{description}
-The comparision of the two strings is case-sensitive.
-The function does not yet take internationalization settings into account.
-\Errors
-None.
-\SeeAlso
-\seef{AnsiCompareText}, \seef{AnsiCompareStr}
-\end{function}
-
-\FPCexample{ex56}
-
-
-\begin{function}{AnsiStrLIComp}
-\Declaration
-Function AnsiStrLIComp(S1, S2: PChar; MaxLen: cardinal): integer;
-\Description
-\var{AnsiStrLIComp} compares the first \var{Maxlen} characters of
-2 \var{PChar} strings, \var{S1} and \var{S2}, and returns the following
-result:
-\begin{description}
-\item[<0]  if \var{S1<S2}.
-\item[0]  if \var{S1=S2}.
-\item[>0]  if \var{S1>S2}.
-\end{description}
-The comparision of the two strings is case-insensitive.
-The function does not yet take internationalization settings into account.
-\Errors
-None.
-\SeeAlso
-\seef{AnsiCompareText}, \seef{AnsiCompareStr}
-\end{function}
-
-\FPCexample{ex57}
-
-
-
-
-\begin{function}{AnsiStrLower}
-\Declaration
-Function AnsiStrLower(Str: PChar): PChar;
-\Description
-\var{AnsiStrLower} converts the PChar \var{Str} to lowercase characters
-and returns the resulting pchar. Note that \var{Str} itself is modified,
-not a copy, as in the case of \seef{AnsiLowerCase}.
-It takes into account the operating system language
-settings when doing this, so spcial characters are converted correctly as
-well.
-
-{\em Remark} On linux, no language setting is taken in account yet.
-\Errors
-None.
-\SeeAlso
-\seef{AnsiStrUpper}, \seef{AnsiLowerCase}
-\end{function}
-
-\FPCexample{ex59}
-
-
-\begin{function}{AnsiStrUpper}
-\Declaration
-Function AnsiStrUpper(Str: PChar): PChar;
-\Description
-\var{AnsiStrUpper} converts the \var{PChar} \var{Str} to uppercase characters
-and returns the resulting string. Note that \var{Str} itself is modified,
-not a copy, as in the case of \seef{AnsiUpperCase}.
-It takes into account the operating system language
-settings when doing this, so spcial characters are converted correctly as
-well.
-
-{\em Remark} On linux, no language setting is taken in account yet.
-\Errors
-None.
-\SeeAlso
-\seef{AnsiUpperCase}, \seef{AnsiStrLower}, \seef{AnsiLowerCase}
-\end{function}
-
-\FPCexample{ex60}
-
-
-\begin{function}{AnsiUpperCase}
-\Declaration
-Function AnsiUpperCase(const s: string): string;
-\Description
-\var{AnsiUpperCase} converts the string \var{S} to uppercase characters
-and returns the resulting string.
-It takes into account the operating system language
-settings when doing this, so spcial characters are converted correctly as
-well.
-
-{\em Remark} On linux, no language setting is taken in account yet.
-\Errors
-None.
-\SeeAlso
-\seef{AnsiStrUpper}, \seef{AnsiStrLower}, \seef{AnsiLowerCase}
-\end{function}
-
-\FPCexample{ex61}
-
-
-\begin{procedure}{AppendStr}
-\Declaration
-Procedure AppendStr(var Dest: String; const S: string);
-\Description
-\var{AppendStr} appends \var{S} to Dest.
-
-This function is provided for Delphi
-compatibility only, since it is completely equivalent to \var{Dest:=Dest+S}.
-\Errors
-None.
-\SeeAlso
-\seep{AssignStr},\seef{NewStr}, \seep{DisposeStr}
-\end{procedure}
-
-\FPCexample{ex62}
-
-
-\begin{procedure}{AssignStr}
-\Declaration
-Procedure AssignStr(var P: PString; const S: string);
-\Description
-\var{AssignStr} allocates \var{S} to P. The old value of \var{P} is
-disposed of.
-
-This function is provided for Delphi compatibility only. \var{AnsiStrings}
-are managed on the heap and should be preferred to the mechanism of
-dynamically allocated strings.
-\Errors
-None.
-\SeeAlso
-\seef{NewStr}, \seep{AppendStr}, \seep{DisposeStr}
-\end{procedure}
-
-\FPCexample{ex63}
-
-
-\begin{function}{BCDToInt}
-\Declaration
-Function BCDToInt(Value: integer): integer;
-\Description
-\var{BCDToInt} converts a \var{BCD} coded integer to a normal integer.
-\Errors
-None.
-\SeeAlso
-\seef{StrToInt}, \seef{IntToStr}
-\end{function}
-
-\FPCexample{ex64}
-
-
-
-\begin{function}{CompareMem}
-\Declaration
-Function CompareMem(P1, P2: Pointer; Length: cardinal): integer;
-\Description
-\var{CompareMem} compares, byte by byte,  2 memory areas pointed
-to by \var{P1} and \var{P2}, for a length of \var{L} bytes.
-
-It returns the following values:
-\begin{description}
-\item[<0] if at some position the byte at \var{P1} is less than the byte at the
-same postion at \var{P2}.
-\item[0] if all \var{L} bytes are the same.
-\item[3]
-\end{description}
-\Errors
-\SeeAlso
-\end{function}
-
-
-\begin{function}{CompareStr}
-\Declaration
-Function CompareStr(const S1, S2: string): Integer;
-\Description
-\var{CompareStr} compares two strings, \var{S1} and \var{S2},
-and returns the following
-result:
-\begin{description}
-\item[<0]  if \var{S1<S2}.
-\item[0]  if \var{S1=S2}.
-\item[>0]  if \var{S1>S2}.
-\end{description}
-The comparision of the two strings is case-sensitive.
-The function does not take internationalization settings into account, it
-simply compares ASCII values.
-\Errors
-None.
-\SeeAlso
-\seef{AnsiCompareText}, \seef{AnsiCompareStr}, \seef{CompareText}
-\end{function}
-
-\FPCexample{ex65}
-
-
-\begin{function}{CompareText}
-\Declaration
-Function CompareText(const S1, S2: string): integer;
-\Description
-\var{CompareText} compares two strings, \var{S1} and \var{S2},
-and returns the following
-result:
-\begin{description}
-\item[<0]  if \var{S1<S2}.
-\item[0]  if \var{S1=S2}.
-\item[>0]  if \var{S1>S2}.
-\end{description}
-The comparision of the two strings is case-insensitive.
-The function does not take internationalization settings into account, it
-simply compares ASCII values.
-\Errors
-None.
-\SeeAlso
-\seef{AnsiCompareText}, \seef{AnsiCompareStr}, \seef{CompareStr}
-\end{function}
-
-\FPCexample{ex66}
-
-
-
-
-\begin{procedurel}{DisposeStr}{DisposeStrSys}
-\Declaration
-Procedure DisposeStr(S: PString);
-\Description
-\var{DisposeStr} removes the dynamically allocated string \var{S} from the
-heap, and releases the occupied memory.
-
-This function is provided for Delphi compatibility only. \var{AnsiStrings}
-are managed on the heap and should be preferred to the mechanism of
-dynamically allocated strings.
-\Errors
-None.
-\SeeAlso
-\seef{NewStr}, \seep{AppendStr}, \seep{AssignStr}
-\end{procedurel}
-
-For an example, see \seep{DisposeStr}.
-
-\begin{function}{FloatToStr}
-\Declaration
-Function FloatToStr(Value: Extended): String;
-\Description
-\var{FloatToStr} converts the floating point variable \var{Value} to a
-string representation.  It will choose the shortest possible notation of the
-two following formats:
-\begin{description}
-\item[Fixed format] will represent the string in fixed notation,
-\item[Decimal format] will represent the string in scientific notation.
-\end{description}
-(more information on these formats can be found in \seef{FloatToStrF})
-\var{FloatToStr} is completely equivalent to a \var{FloatToStrF(Value, ffGeneral,
-15, 0);} call.
-\Errors
-None.
-\SeeAlso
-\seef{FloatToStrF}, \seef{FormatFloat}, \seef{StrToFloat}
-\end{function}
-
-\FPCexample{ex67}
-
-
-\begin{function}{FloatToStrF}
-\Declaration
-Function FloatToStrF(Value: Extended; format: TFloatFormat; Precision, Digits: Integer): String;
-\Description
-\var{FloatToStrF} converts the floating point number \var{value} to a string
-representation, according to the settings of the parameters \var{Format},
-\var{Precision} and \var{Digits}.
-
-The meaning of the \var{Precision} and \var{Digits} parameter depends on the
-\var{Format} parameter. The format is controlled mainly by the \var{Format}
-parameter. It can have one of the following values:
-\begin{description}
-\item[ffcurrency] Money format. \var{Value} is converted to a string using
-the global variables \var{CurrencyString}, \var{CurrencyFormat} and
-\var{NegCurrencyFormat}. The \var{Digits} paramater specifies the number of digits
-following the decimal point and should be in the range -1 to 18. If Digits
-equals \var{-1}, \var{CurrencyDecimals} is assumed. The \var{Precision} parameter is ignored.
-%
-\item[ffExponent] Scientific format. \var{Value} is converted to a
-string using scientific notation: 1 digit before the decimal point, possibly
-preceded by a minus sign if \var{Value} is negative. The number of
-digits after the decimal point is controlled by \var{Precision} and must lie
-in the range 0 to 15.
-%
-\item[ffFixed] Fixed point format. \var{Value} is converted to a string
-using fixed point notation. The result is composed of all digits of the
-integer part of \var{Value}, preceded by a minus sign if \var{Value} is
-negative. Following the integer part is \var{DecimalSeparator} and then the
-fractional part of \var{Value}, rounded off to \var{Digits} numbers.
-If the number is too large then the result will be in scientific notation.
-%
-\item[ffGeneral] General number format. The argument is converted to a
-string using \var{ffExponent} or \var{ffFixed} format, depending on wich one
-gives the shortest string. There will be no trailing zeroes. If \var{Value}
-is less than \var{0.00001} or if the number of decimals left of the decimal
-point is larger than \var{Precision} then scientific notation is used, and
-\var{Digits} is the minimum number of digits in the exponent. Otherwise
-\var{Digits} is ignored.
-\item[ffnumber] Is the same as \var{ffFixed}, except that thousand separators
-are inserted in the resultig string.
-\end{description}
-\Errors
-None.
-\SeeAlso
-\seef{FloatToStr}, \seef{FloatToText}
-\end{function}
-
-\FPCexample{ex68}
-
-
-\begin{function}{FloatToText}
-\Declaration
-Function FloatToText(Buffer : Pchar;Value: Extended; Format: TFloatFormat; Precision, Digits: Integer): Longint;
-\Description
-\var{FloatToText} converts the floating point variable \var{Value} to a
-string representation and stores it in \var{Buffer}.  The conversion is
-giverned by \var{format}, \var{Precisison} and \var{Digits}.
-more information on these parameters can be found in \seef{FloatToStrF}.
-\var{Buffer} should point to enough space to hold the result. No checking on
-this is performed.
-
-The result is the number of characters that was copied in \var{Buffer}.
-\Errors
-None.
-\SeeAlso
-\seef{FloatToStr}, \seef{FloatToStrF}
-\end{function}
-
-\FPCexample{ex69}
-
-
-\begin{procedure}{FmtStr}
-\Declaration
-Procedure (Var Res: String; Const Fmt : String; Const args: Array of const);
-\Description
-\var{FmtStr} calls \seef{Format} with \var{Fmt} and \var{Args} as arguments,
-and stores the result in \var{Res}. For more information on how the
-resulting string is composed, see \seef{Format}.
-\Errors
-In case of error, a \var{EConvertError} exception is raised.
-\SeeAlso
-\seef{Format}, \seef{FormatBuf}.
-\end{procedure}
-
-\FPCexample{ex70}
-
-
-\begin{function}{Format}
-\Declaration
-Function Format(Const Fmt : String; const Args : Array of const) : String;
-\Description
-Format replaces all placeholders in\var{Fmt} with the arguments passed in
-\var{Args} and returns the resulting string. A placeholder looks as follows:
-\begin{verbatim}
-'%' [Index':'] ['-'] [Width] ['.' Precision] ArgType
-\end{verbatim}
-elements between single quotes must be typed as shown without the quotes,
-and elements between square brackets \var{[ ]} are optional. The meaning
-of the different elements is shown below:
-\begin{description}
-\item['\%'] starts the placeholder. If you want to insert a literal
-\var{\%} character, then you must insert two of them : \var{\%\%}.
-\item[Index ':'] takes the \var{Index}-th element in the argument array
-as the element to insert.
-\item['-'] tells \var{Format} to left-align the inserted text. The default
-behaviour is to right-align inserted text. This can only take effect if the
-\var{Width} element is also specified.
-\item[Width] the inserted string must have at least have \var{Width}
-characters. If not, the inserted string will be padded with spaces. By
-default, the string is left-padded, resulting in a right-aligned string.
-This behaviour can be changed by the \var{'-'} character.
-\item['.' Precision] Indicates the precision to be used when converting
-the argument. The exact meaning of this parameter depends on \var{ArgType}.
-\end{description}
-The \var{Index}, \var{Width} and \var{Precision} parameters can be replaced
-by \var{*}, in which case their value will be read from the next element in
-the \var{Args} array. This value must be an integer, or an
-\var{EConvertError} exception will be raised.
-
-The argument type is determined from \var{ArgType}. It can have one of the
-following values (case insensitive):
-\begin{description}
-\item[D] Decimal format. The next argument in the \var{Args} array should be
-an integer. The argument is converted to a decimal string,. If precision is
-specified, then the string will have at least \var{Precision} digits in it.
-If needed, the string is (left) padded with zeroes.
-\item[E] scientific format. The next argument in the \var{Args} array should
-be a Floating point value. The argument is converted to a decimal string
-using scientific notation, using \seef{FloatToStrF}, where the optional
-precision is used to specify the total number of decimals. (defalt a valueof
-15 is used). The exponent is formatted using maximally 3 digits.
-
-In short, the \var{E} specifier formats it's arguument as follows:
-\begin{verbatim}
-FloatToStrF(Argument,ffexponent,Precision,3)
-\end{verbatim}
-
-\item[F] fixed point format. The next argument in the \var{Args} array
-should be a floating point value. The argument is converted to a
-decimal string, using fixed notation (see \seef{FloatToStrF}).
-\var{Precision} indicates the number of digits following the
-decimal point.
-
-In short, the \var{F} specifier formats it's arguument as follows:
-\begin{verbatim}
-FloatToStrF(Argument,ffFixed,ffixed,9999,Precision)
-\end{verbatim}
-
-\item[G] General number format. The next argument in the \var{Args} array
-should be a floating point value. The argument is converted to a decimal
-string using fixed point notation or scientific notation, depending on which
-gives the shortest result. \var{Precision} is used to determine the number
-of digits after the decimal point.
-
-In short, the \var{G} specifier formats it's arguument as follows:
-\begin{verbatim}
-FloatToStrF(Argument,ffGeneral,Precision,3)
-\end{verbatim}
-
-\item[M] Currency format. the next argument in the var{Args} array must
-be a floating point value. The argument is converted to a decimal string
-using currency notation. This means that fixed-point notation is used, but
-that the currency symbol is appended. If precision is specified, then
-then it overrides the \var{CurrencyDecimals} global variable used in the
-\seef{FloatToStrF}
-
-In short, the \var{M} specifier formats it's arguument as follows:
-\begin{verbatim}
-FloatToStrF(Argument,ffCurrency,9999,Precision)
-\end{verbatim}
-
-\item[N] Number format. This is the same as fixed point format, except that
-thousand separators are inserted in the resulting string.
-
-\item[P] Pointer format. The next argument in the \var{Args} array must be a
-pointer (typed or untyped). The pointer value is converted to a string of
-length 8, representing the hexadecimal value of the pointer.
-
-\item[S] String format. The next argument in the \var{Args} array must be
-a string. The argument is simply copied to the result string. If
-\var{Precision} is specified, then only \var{Precision} characters are
-copied to the result string.
-
-\item[X] hexadecimal format. The next argument in the \var{Args} array must
-be an integer. The argument is converted to a hexadecimal string with just
-enough characters to contain the value of the integer. If \var{Precision}
-is specified then the resulting hexadecimal representation will have at
-least \var{Precision} characters in it (with a maximum value of 32).
-\end{description}
-\Errors
-In case of error, an \var{EConversionError} exception is raised. Possible
-errors are:
-\begin{enumerate}
-\item Errors in the format specifiers.
-\item The next argument is not of the type needed by a specifier.
-\item The number of arguments is not sufficient for all format specifiers.
-\end{enumerate}
-\SeeAlso
-\seef{FormatBuf}
-\end{function}
-
-\FPCexample{ex71}
-
-
-\begin{function}{FormatBuf}
-\Declaration
-Function FormatBuf(Var Buffer; BufLen : Cardinal; Const Fmt; fmtLen : Cardinal; Const Args : Array of const) : Cardinal;
-\Description
-\var{Format}
-\Errors
-\SeeAlso
-\end{function}
-
-\FPCexample{ex72}
-
-\begin{function}{FormatFloat}
-\Declaration
-Function FormatFloat(Const format: String; Value: Extended): String;
-\Description
-FormatFloat formats the floating-point value given by \var{Value} using 
-the format specifications in \var{Format}. The format specifier can give
-format specifications for positive, negative or zero values (separated by 
-a semicolon).
-
-
-If the formatspecifier is empty or the value needs more than 18 digits to
-be correctly represented, the result is formatted with a call to 
-\seef{FloatToStrF} with the \var{ffGeneral} format option.
-
-The following format specifiers are supported:
-\begin{description}
-\item[0] is a digit place holder. If there is a corresponding digit in 
-the value being formatted, then it replaces the 0. If not, the 0 is left
-as-is.
-\item[\#] is also a digit place holder. If there is a corresponding digit in
-the value being formatted, then it replaces the \#. If not, it is removed.
-by a space.
-\item[.] determines the location of the decimal point. Only the first '.'
-character is taken into account. If the value contains digits after the
-decimal point, then it is replaced by the value of the \var{DecimalSeparator}
-character.
-\item[,] determines the use of the thousand separator character in the
-output string. If the format string contains one or more ',' charactes, 
-then thousand separators will be used. The \var{ThousandSeparator} character
-is used.
-\item[E+] determines the use of scientific notation. If 'E+' or 'E-' (or
-their lowercase counterparts) are present then scientific notation is used.
-The number of digits in the output string is determined by the number of
-\var{0} characters after the '\var{E+}'
-\item[;] This character separates sections for positive, negative, and zero numbers in the
-format string.	
-\end{description}
-\Errors
-If an error occurs, an exception is raised.
-\SeeAlso
-\seef{FloatToStr}
-\end{function}
-
-\FPCexample{ex89}
-
-\begin{function}{IntToHex}
-\Declaration
-Function IntToHex(Value: integer; Digits: integer): string;
-\Description
-\var{IntToHex} converts \var{Value} to a hexadecimal string
-representation. The result will contain at least \var{Digits}
-characters. If \var{Digits} is less than the needed number of characters,
-the string will NOT be truncated. If \var{Digits} is larger than the needed
-number of characters, the result is padded with zeroes.
-\Errors
-None.
-\SeeAlso
-\seef{IntToStr}, \var{StrToInt}
-\end{function}
-
-\FPCexample{ex73}
-
-
-\begin{function}{IntToStr}
-\Declaration
-Function IntToStr(Value: integer): string;
-\Description
-\var{IntToStr} coverts \var{Value} to it's string representation.
-The resulting string has only as much characters as needed to represent
-the value. If the value is negative a minus sign is prepended to the
-string.
-\Errors
-None.
-\SeeAlso
-\seef{IntToHex}, \seef{StrToInt}
-\end{function}
-
-\FPCexample{ex74}
-
-
-\begin{function}{IsValidIdent}
-\Declaration
-Function IsValidIdent(const Ident: string): boolean;
-\Description
-\var{IsValidIdent} returns \var{True} if \var{Ident} can be used as a
-compoent name. It returns \var{False} otherwise. \var{Ident} must consist of
-a letter or underscore, followed by a combination of letters, numbers or
-underscores to be a valid identifier.
-\Errors
-None.
-\SeeAlso
-\end{function}
-
-\FPCexample{ex75}
-
-
-\begin{function}{LastDelimiter}
-\Declaration
-Function LastDelimiter(const Delimiters, S: string): Integer;
-\Description
-\var{LastDelimiter} returns the {\em last} occurrence of any character in
-the set \var{Delimiters} in the string \var{S}.
-\Errors
-\SeeAlso
-\end{function}
-
-\FPCexample{ex88}
-
-
-\begin{function}{LeftStr}
-\Declaration
-Function LeftStr(const S: string; Count: integer): string;
-\Description
-\var{LeftStr} returns the \var{Count} leftmost characters of \var{S}.
-It is equivalent to a call to \var{Copy(S,1,Count)}.
-\Errors
-None.
-\SeeAlso
-\seef{RightStr}, \seef{TrimLeft}, \seef{TrimRight}, \seef{Trim}
-\end{function}
-
- \FPCexample{ex76}
-
-
-\begin{function}{LoadStr}
-\Declaration
-Function LoadStr(Ident: integer): string;
-\Description
-This function is not yet implemented. resources are not yet supported.
-\Errors
-\SeeAlso
-\end{function}
-
-\begin{function}{LowerCase}
-\Declaration
-Function LowerCase(const s: string): string;
-\Description
-\var{LowerCase} returns the lowercase equivalent of \var{S}. Ansi characters
-are not taken into account, only ASCII codes below 127 are converted. It is
-completely equivalent to the lowercase function of the system unit, and is
-provided for compatiibility only.
-\Errors
-None.
-\SeeAlso
-\seef{AnsiLowerCase}, \seef{UpperCase}, \seef{AnsiUpperCase}
-\end{function}
-
-\FPCexample{ex77}
-
-
-\begin{functionl}{NewStr}{NewStrSys}
-\Declaration
-Function NewStr(const S: string): PString;
-\Description
-\var{NewStr} assigns a new dynamic string on the heap, copies \var{S} into
-it, and returns a pointer to the newly assigned string.
-
-This function is obsolete, and shouldn't be used any more. The
-\var{AnsiString} mechanism also allocates ansistrings on the heap, and
-should be preferred over this mechanism.
-\Errors
-If not enough memory is present, an EOutOfMemory exception will be raised.
-\SeeAlso
-\seep{AssignStr}, \seepl{DisposeStr}{DisposeStrSys}
-\end{functionl}
-
-For an example, see \seep{AssignStr}.
-
-\begin{function}{QuotedStr}
-\Declaration
-Function QuotedStr(const S: string): string;
-\Description
-\var{QuotedStr} returns the string \var{S}, quoted with single quotes. This means
-that \var{S} is enclosed in single quotes, and every single quote in \var{S}
-is doubled. It is equivalent to a call to \var{AnsiQuotedStr(s, '''')}.
-\Errors
-None.
-\SeeAlso
-\seef{AnsiQuotedStr}, \seef{AnsiExtractQuotedStr}.
-\end{function}
-
-\FPCexample{ex78}
-
-
-
-\begin{function}{RightStr}
-\Declaration
-Function RightStr(const S: string; Count: integer): string;
-\Description
-\var{RightStr} returns the \var{Count} rightmost characters of \var{S}.
-It is equivalent to a call to \var{Copy(S,Length(S)+1-Count,Count)}.
-
-If \var{Count} is larger than the actual length of \var{S} only the real
-length will be used.
-\Errors
-None.
-\SeeAlso
-\seef{LeftStr},\seef{Trim}, \seef{TrimLeft}, \seef{TrimRight}
-\end{function}
-
-\FPCexample{ex79}
-
-
-\begin{function}{StrFmt}
-\Declaration
-Function StrFmt(Buffer,Fmt : PChar; Const args: Array of const) : Pchar;
-\Description
-\var{StrFmt} will format \var{fmt} with \var{Args}, as the \seef{Format}
-function does, and it will store the result in \var{Buffer}. The function
-returns \var{Buffer}. \var{Buffer} should point to enough space to contain
-the whole result.
-\Errors
-for a list of errors, see \seef{Format}.
-\SeeAlso
-\seef{StrLFmt}, \seep{FmtStr}, \seef{Format}, \seef{FormatBuf}
-\end{function}
-
-\FPCexample{ex80}
-
-
-\begin{function}{StrLFmt}
-\Declaration
-Function StrLFmt(Buffer : PCHar; Maxlen : Cardinal;Fmt : PChar; Const args: Array of const) : Pchar;
-\Description
-\var{StrLFmt} will format \var{fmt} with \var{Args}, as the \seef{Format}
-function does, and it will store maximally \var{Maxlen characters} of the
-result in \var{Buffer}. The function returns \var{Buffer}. \var{Buffer}
-should point to enough space to contain \var{MaxLen} characters.
-\Errors
-for a list of errors, see \seef{Format}.
-\SeeAlso
-\seef{StrFmt}, \seep{FmtStr}, \seef{Format}, \seef{FormatBuf}
-\end{function}
-
-\FPCexample{ex81}
-
-\begin{function}{StrToFloat}
-\Declaration
-Function StrToFloat(Const S : String) : Extended;
-\Description
-\var{StrToFloat} converts the string \var{S} to a floating point value.
-\var{S} should contain a valid stroing representation of a floating point 
-value (either in decimal or scientific notation). If the string
-contains a decimal value, then the decimal separator character can either be
-a '.' or the value of the \var{DecimalSeparator} variable.
-\Errors
-If the string \var{S} doesn't contain a valid floating point string, then an
-exception will be raised.
-\SeeAlso
-\seef{TextToFloat},\seef{FloatToStr},\seef{FormatFloat},\seef{StrToInt}
-\end{function}
-
-\FPCexample{ex90}
-
-
-\begin{function}{StrToInt}
-\Declaration
-Function StrToInt(const s: string): integer;
-\Description
-\var{StrToInt} will convert the string \var{S}to an integer.
-If the string contains invalid characters or has an invalid format,
-then an \var{EConvertError} is raised.
-
-To be successfully converted, a string can contain a combination
-of \var{numerical} characters, possibly preceded by a minus sign (\var{-}).
-Spaces are not allowed.
-\Errors
-In case of error, an \var{EConvertError} is raised.
-\SeeAlso
-\seef{IntToStr}, \seef{StrToIntDef}
-\end{function}
-
-\FPCexample{ex82}
-
-
-\begin{function}{StrToIntDef}
-\Declaration
-Function StrToIntDef(const S: string; Default: integer): integer;
-\Description
-\var{StrToIntDef} will convert a string to an integer. If the string contains
-invalid characters or has an invalid format, then \var{Default} is returned.
-
-To be successfully converted, a string can contain a combination of
-\var{numerical} characters, possibly preceded by a minus sign (\var{-}).
-Spaces are not allowed.
-\Errors
-None.
-\SeeAlso
-\seef{IntToStr}, \seef{StrToInt}
-\end{function}
-
-\FPCexample{ex83}
-
-\begin{function}{TextToFloat}
-\Declaration
-Function TextToFloat(Buffer: PChar; Var Value: Extended): Boolean;
-\Description
-\var{TextToFloat} converts the string in \var{Buffer} to a floating point 
-value. \var{Buffer} should contain a valid stroing representation of a 
-floating point value (either in decimal or scientific notation). 
-If the buffer contains a decimal value, then the decimal separator 
-character can either be a '.' or the value of the \var{DecimalSeparator} 
-variable.
-
-The function returns \var{True} if the conversion was successful.
-\Errors
-If there is an invalid character in the buffer, then the function returns
-\var{False}
-\SeeAlso
-\seef{StrToFloat},\seef{FloatToStr}, \seef{FormatFloat}
-\end{function}
-
-\FPCexample{ex91}
-
-\begin{function}{Trim}
-\Declaration
-Function Trim(const S: string): string;
-\Description
-\var{Trim} strips blank characters (spaces) at the beginning and end of \var{S}
-and returns the resulting string. Only \var{\#32} characters are stripped.
-
-If the string contains only spaces, an empty string is returned.
-\Errors
-None.
-\SeeAlso
-\seef{TrimLeft}, \seef{TrimRight}
-\end{function}
-
-\FPCexample{ex84}
-
-
-\begin{function}{TrimLeft}
-\Declaration
-Function TrimLeft(const S: string): string;
-\Description
-\var{TrimLeft} strips blank characters (spaces) at the beginning of \var{S}
-and returns the resulting string. Only \var{\#32} characters are stripped.
-
-If the string contains only spaces, an empty string is returned.
-\Errors
-None.
-\SeeAlso
-\seef{Trim}, \seef{TrimRight}
-\end{function}
-
-\FPCexample{ex85}
-
-
-\begin{function}{TrimRight}
-\Declaration
-Function TrimRight(const S: string): string;
-\Description
-\var{Trim} strips blank characters (spaces) at the end of \var{S}
-and returns the resulting string. Only \var{\#32} characters are stripped.
-
-If the string contains only spaces, an empty string is returned.
-\Errors
-None.
-\SeeAlso
-\seef{Trim}, \seef{TrimLeft}
-\end{function}
-
-\FPCexample{ex86}
-
-
-
-\begin{function}{UpperCase}
-\Declaration
-Function UpperCase(const s: string): string;
-\Description
-\var{UpperCase} returns the uppercase equivalent of \var{S}. Ansi characters
-are not taken into account, only ASCII codes below 127 are converted. It is
-completely equivalent to the \var{UpCase} function of the system unit, and is
-provided for compatiibility only.
-\Errors
-None.
-\SeeAlso
-\seef{AnsiLowerCase}, \seef{LowerCase}, \seef{AnsiUpperCase}
-\Errors
-\SeeAlso
-\end{function}
-
-\FPCexample{ex87}
-
-

docs/typinfo.tex

@@ -1,1043 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 2001, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA.
-%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% The TYPINFO unit
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\chapter{The TYPINFO unit}
-\FPCexampledir{typinfex}
-The \file{TypeInfo} unit contains many routines which can be used for
-the querying of the Run-Time Type Information (RTTI) which is generated
-by the compiler for classes that are compiled under the \var{\{\$M+\}}
-switch. This information can be used to retrieve or set property values
-for published properties for totally unknown classes. In particular, it
-can be used to stream classes. The \var{TPersistent} class in the 
-\file{Classes} unit is compiled in the \var{\{\$M+\}} state and serves
-as the base class for all classes that need to be streamed.
-
-The unit should be compatible to the Delphi 5 unit with the same name. 
-The only calls that are still missing are the Variant calls, since \fpc
-does not support the variant type yet.
-
-The examples in this chapter use a \file{rttiobj} file, which contains
-an object that has a published property of all supported types. It also
-contains some auxiliary routines and definitions.
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Constants, Types and variables
-\section{Constants, Types and variables}
-\subsection{Constants}
-The following constants are used in the implementation section of the unit.
-
-\begin{verbatim}
-BooleanIdents: array[Boolean] of String = ('False', 'True');
-DotSep: String = '.';
-\end{verbatim}
-The following constants determine the access method for the \var{Stored} 
-identifier of a property as used in the \var{PropProcs} field of the 
-\var{TPropInfo} record:
-\begin{verbatim}
-ptField = 0;
-ptStatic = 1;
-ptVirtual = 2;
-ptConst = 3;
-\end{verbatim}
-The following typed constants are used for easy selection of property types.
-\begin{verbatim}
-tkAny = [Low(TTypeKind)..High(TTypeKind)];
-tkMethods = [tkMethod];
-tkProperties = tkAny-tkMethods-[tkUnknown];
-\end{verbatim}
-
-\subsection{types}
-The following pointer types are defined:
-\begin{verbatim}
-PShortString =^ShortString;
-PByte        =^Byte;
-PWord        =^Word;
-PLongint     =^Longint;
-PBoolean     =^Boolean;
-PSingle      =^Single;
-PDouble      =^Double;
-PExtended    =^Extended;
-PComp        =^Comp;
-PFixed16     =^Fixed16;
-Variant      = Pointer;
-\end{verbatim}
-
-The \var{TTypeKind} determines the type of a property:
-\begin{verbatim}
-TTypeKind = (tkUnknown,tkInteger,tkChar,tkEnumeration,
-             tkFloat,tkSet,tkMethod,tkSString,tkLString,tkAString,
-             tkWString,tkVariant,tkArray,tkRecord,tkInterface,
-             tkClass,tkObject,tkWChar,tkBool,tkInt64,tkQWord,
-             tkDynArray,tkInterfaceRaw);
-tkString = tkSString;
-\end{verbatim}
-\var{tkString} is an alias that is introduced for Delphi compatibility.
-
-If the property is and ordinal type, then \var{TTOrdType} determines the 
-size and sign of the ordinal type:
-\begin{verbatim}
-TTOrdType = (otSByte,otUByte,otSWord,otUWord,otSLong,otULong);
-\end{verbatim}
-The size of a float type is determined by \var{TFloatType}:
-\begin{verbatim}
-TFloatType = (ftSingle,ftDouble,ftExtended,ftComp,ftCurr,
-              ftFixed16,ftFixed32);
-\end{verbatim}
-A method property (e.g. an event) can have one of several types:
-\begin{verbatim}
-TMethodKind = (mkProcedure,mkFunction,mkConstructor,mkDestructor,
-               mkClassProcedure, mkClassFunction);
-\end{verbatim}
-The kind of parameter to a method is determined by \var{TParamFlags}:
-\begin{verbatim}
-TParamFlags = set of (pfVar,pfConst,pfArray,pfAddress,pfReference,pfOut);
-\end{verbatim}
-Interfaces are described further with \var{TntfFlags}:
-\begin{verbatim}
-TIntfFlags = set of (ifHasGuid,ifDispInterface,ifDispatch);
-\end{verbatim}
-The following defines a set of \var{TTypeKind}:
-\begin{verbatim}
-TTypeKinds = set of TTypeKind;
-\end{verbatim}
-The \var{TypeInfo} function returns a pointer to a \var{TTypeInfo} record:
-\begin{verbatim}
-TTypeInfo = record
-  Kind : TTypeKind;
-  Name : ShortString;
-end;
-PTypeInfo = ^TTypeInfo;
-PPTypeInfo = ^PTypeInfo;
-\end{verbatim}
-Note that the Name is stored with as much bytes as needed to store the name,
-it is not padded to 255 characters. 
-The type data immediatly follows the \var{TTypeInfo} record as a \var{TTypeData} record:
-\begin{verbatim}
-PTypeData = ^TTypeData;
-TTypeData = packed record
-case TTypeKind of
-  tkUnKnown,tkLString,tkWString,tkAString,tkVariant:
-    ();
-  tkInteger,tkChar,tkEnumeration,tkWChar:
-    (OrdType : TTOrdType;
-     case TTypeKind of
-       tkInteger,tkChar,tkEnumeration,tkBool,tkWChar : (
-         MinValue,MaxValue : Longint;
-         case TTypeKind of
-           tkEnumeration: (
-             BaseType : PTypeInfo;
-             NameList : ShortString
-           )
-         );
-       tkSet: (
-             CompType : PTypeInfo
-         )
-     );
-  tkFloat: (
-    FloatType : TFloatType
-    );
-  tkSString:
-    (MaxLength : Byte);
-  tkClass:
-    (ClassType : TClass;
-     ParentInfo : PTypeInfo;
-     PropCount : SmallInt;
-     UnitName : ShortString
-     );
-  tkMethod:
-    (MethodKind : TMethodKind;
-     ParamCount : Byte;
-     ParamList : array[0..1023] of Char
-     {in reality ParamList is a array[1..ParamCount] of:
-	  record
-	    Flags : TParamFlags;
-	    ParamName : ShortString;
-	    TypeName : ShortString;
-	  end;
-	followed by
-	  ResultType : ShortString}
-    );
-  tkInt64:
-   (MinInt64Value, MaxInt64Value: Int64);
-  tkQWord:
-   (MinQWordValue, MaxQWordValue: QWord);
-  tkInterface:
-	();
-end;
-\end{verbatim}
-If the typeinfo kind is \var{tkClass}, then the property 
-information follows the \var{UnitName} string, as an array of \var{TPropInfo} records.
-
-The \var{TPropData} record is not used, but is provided for completeness and
-compatibility with Delphi.
-\begin{verbatim}
-TPropData = packed record
-  PropCount : Word;
-  PropList : record end;
-end;
-\end{verbatim}
-The \var{TPropInfo} record describes one published property of a class:
-\begin{verbatim}
-PPropInfo = ^TPropInfo;
-TPropInfo = packed record
-  PropType : PTypeInfo;
-  GetProc : Pointer;
-  SetProc : Pointer;
-  StoredProc : Pointer;
-  Index : Integer;
-  Default : Longint;
-  NameIndex : SmallInt;
-  PropProcs : Byte;
-  Name : ShortString;
-end;
-\end{verbatim}
-The \var{Name} field is stored not with 255 characters, but with just as many characters
-as required to store the name.
-\begin{verbatim}
-TProcInfoProc = procedure(PropInfo : PPropInfo) of object;
-\end{verbatim}
-The following pointer and array types are used for typecasts:
-\begin{verbatim}
-PPropList = ^TPropList;
-TPropList = array[0..65535] of PPropInfo;
-\end{verbatim}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Functions and procedures by category
-\section{Function list by category}
-What follows is a listing of the available functions, grouped by category.
-For each function there is a reference to the page where the function
-can be found.
-
-\subsection{Examining published property information}
-Functions for retrieving or examining property information
-\begin{funclist}
-\funcref{FindPropInfo}{Getting property type information, With error checking.}
-\funcref{GetPropInfo}{Getting property type information, No error checking.}
-\funcref{GetPropInfos}{Find property information of a certain kind}
-\funcref{GetObjectPropClass}{Return the declared class of an object property }
-\funcref{GetPropList}{Get a list of all published properties}
-\funcref{IsPublishedProp}{Is a property published}
-\funcref{IsStoredProp}{Is a property stored}
-\funcref{PropIsType}{Is a property of a certain kind}
-\funcref{PropType}{Return the type of a property}
-\end{funclist}
-
-\subsection{Getting or setting property values}
-Functions to set or set a property's value.
-\begin{funclist}
-\funcref{GetEnumProp}{Return the value of an enumerated type property}
-\funcref{GetFloatProp}{Return the value of a float property}
-\funcref{GetInt64Prop}{Return the value of an Int64 property}
-\funcref{GetMethodProp}{Return the value of a procedural type property}
-\funcref{GetObjectProp}{Return the value of an object property}
-\funcref{GetOrdProp}{Return the value of an ordinal type property}
-\funcref{GetPropValue}{Return the value of a property as a variant}
-\funcref{GetSetProp}{Return the value of a set property}
-\funcref{GetStrProp}{Return the value of a string property}
-\funcref{GetVariantProp}{Return the value of a variant property}
-\funcref{SetEnumProp}{Set the value of an enumerated type property}
-\funcref{SetFloatProp}{Set the value of a float property}
-\funcref{SetInt64Prop}{Set the value of an Int64 property}
-\funcref{SetMethodProp}{Set the value of a procedural type property}
-\funcref{SetObjectProp}{Set the value of an object property}
-\funcref{SetOrdProp}{Set the value of an ordinal type property}
-\funcref{SetPropValue}{Set the value of a property trhough a variant}
-\funcref{SetSetProp}{Set the value of a set property}
-\funcref{SetStrProp}{Set the value of a string property}
-\funcref{SetVariantProp}{Set the value of a variant property}
-\end{funclist}
-
-\subsection{Auxiliary functions}
-\begin{funclist}
-\funcref{GetEnumName}{Get an enumerated type element name}
-\funcref{GetEnumValue}{Get ordinal number of an enumerated tye, based on the
-name.}
-\funcref{GetTypeData}{Skip type name and return a pointer to the type data}
-\funcref{SetToString}{Convert a set to its string representation}
-\funcref{StringToSet}{Convert a string representation of a set to a set}
-\end{funclist}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% Functions and procedures
-\section{Functions and Procedures}
-
-\begin{function}{FindPropInfo}
-\Declaration
-Function FindPropInfo(AClass:TClass;const PropName: string): PPropInfo;\\
-Function FindPropInfo(Instance: TObject; const PropName: string): PPropInfo;   
-\Description
-\var{FindPropInfo} examines the published property information of a class and
-returns a pointer to the property information for property \var{PropName}.
-The class to be examined can be specified in one of two ways:
-\begin{description}
-\item[AClass] a class pointer.
-\item[Instance] an instance of the class to be investigated.
-\end{description}
-If the property does not exist, a \var{EPropertyError} exception will be
-raised. The \seef{GetPropInfo} function has the same function as the
-\var{FindPropInfo} function, but returns \var{Nil} if the property does not
-exist.
-\Errors
-Specifying an invalid property name in \var{PropName} will result in an
-\var{EPropertyError} exception.
-\SeeAlso
-\seef{GetPropInfo}, \seef{GetPropList}, \seep{GetPropInfos}
-\end{function}
-
-\FPCexample{ex14}
-
-\begin{function}{GetEnumName}
-\Declaration
-Function GetEnumName(TypeInfo : PTypeInfo;Value : Integer) : string;
-\Description
-\var{GetEnumName} scans the type information for the enumeration type
-described by \var{TypeInfo} and returns the name of the enumeration 
-constant for the element with ordinal value equal to \var{Value}.
-
-If \var{Value} is out of range, the first element of the enumeration type
-is returned. The result is lowercased, but this may change in the future.
-
-This can be used in combination with \var{GetOrdProp} to stream a property
-of an enumerated type.
-\Errors
-No check is done to determine whether \var{TypeInfo} really points to the 
-type information for an enumerated type. 
-\SeeAlso
-\seef{GetOrdProp}, \seef{GetEnumValue}
-\end{function}
-
-\FPCexample{ex9}
-
-\begin{function}{GetEnumProp}
-\Declaration
-Function GetEnumProp(Instance: TObject;const PropInfo: PPropInfo): string;\\
-Function GetEnumProp(Instance: TObject;const PropName: string): string;       
-\Description
-\var{GetEnumProp} returns the value of an property of an enumerated type
-and returns the name of the enumerated value for the objetc \var{Instance}. 
-The property whose value must be returned can be specified by its property 
-info in \var{PropInfo} or by its name in \var{PropName}
-\Errors
-No check is done to determine whether \var{PropInfo} really points to the 
-property information for an enumerated type. 
-Specifying an invalid property name in \var{PropName} will result in an
-\var{EPropertyError} exception.
-\SeeAlso
-\seep{SetEnumProp} \seef{GetOrdProp}, \seef{GetStrProp},
-\seef{GetInt64Prop},\seef{GetMethodProp}, \seef{GetSetProp},
-\seef{GetObjectProp}, \seef{GetEnumProp}
-\end{function}
-
-\FPCexample{ex2}
-
-\begin{function}{GetEnumValue}
-\Declaration
-Function GetEnumValue(TypeInfo : PTypeInfo;const Name : string) : Integer;
-\Description
-\var{GetEnumValue} scans the type information for the enumeration type
-described by \var{TypeInfor} and returns the ordinal value for the element
-in the enumerated type that has identifier \var{Name}. The identifier is
-searched in a case-insensitive manner.
-
-This can be used to set the value of enumerated properties from a stream. 
-\Errors
-If \var{Name} is not found in the list of enumerated values, then -1 is
-returned. No check is done whether \var{TypeInfo} points to the type information
-for an enumerated type. 
-\SeeAlso
-\seef{GetEnumName}, \seep{SetOrdProp}
-\end{function}
-
-For an example, see \seef{GetEnumName}.
-
-\begin{function}{GetFloatProp}
-\Declaration
-Function GetFloatProp(Instance : TObject;PropInfo : PPropInfo) : Extended;\\
-Procedure SetFloatProp(Instance: TObject; const PropName: string; Value: Extended);
-\Description
-\var{GetFloatProp} returns the value of the float property described by 
-\var{PropInfo} or with name \var{Propname} for the object \var{Instance}. 
-All float types are converted
-to extended.
-\Errors
-No checking is done whether \var{Instance} is non-nil, or whether
-\var{PropInfo} describes a valid float property of \var{Instance}.
-Specifying an invalid property name in \var{PropName} will result in an
-\var{EPropertyError} exception.
-\SeeAlso
-\seep{SetFloatProp}, \seef{GetOrdProp}, \seef{GetStrProp},
-\seef{GetInt64Prop},\seef{GetMethodProp}, \seef{GetSetProp},
-\seef{GetObjectProp}, \seef{GetEnumProp}
-\end{function}
-
-\FPCexample{ex4}
-
-\begin{function}{GetInt64Prop}
-\Declaration
-Function GetInt64Prop(Instance: TObject; PropInfo: PPropInfo): Int64;\\
-Function GetInt64Prop(Instance: TObject; const PropName: string): Int64;
-\Description
-{\em Publishing of Int64 properties is not yet supported by \fpc. This
-function is provided for Delphi compatibility only at the moment.}
-
-\var{GetInt64Prop} returns the value of the property of type
-\var{Int64} that is described by \var{PropInfo} or with name \var{Propname} 
-for the object \var{Instance}.
-
-\Errors
-No checking is done whether \var{Instance} is non-nil, or whether
-\var{PropInfo} describes a valid \var{Int64} property of \var{Instance}.
-Specifying an invalid property name in \var{PropName} will result in an
-\var{EPropertyError} exception
-\SeeAlso
-\seep{SetInt64Prop}, \seef{GetOrdProp}, \seef{GetStrProp},
-\seef{GetFloatProp}, \seef{GetMethodProp}, \seef{GetSetProp},
-\seef{GetObjectProp}, \seef{GetEnumProp}
-\end{function}
-
-\FPCexample{ex15}
-
-\begin{function}{GetMethodProp}
-\Declaration
-Function GetMethodProp(Instance : TObject;PropInfo : PPropInfo) : TMethod;\\
-Function GetMethodProp(Instance: TObject; const PropName: string): TMethod;
-\Description
-\var{GetMethodProp} returns the method the property described by
-\var{PropInfo} or with name \var{Propname} for object \var{Instance}.
-The return type \var{TMethod} is defined in the \file{SysUtils} unit as:
-\begin{verbatim}
-TMethod = packed record
-  Code, Data: Pointer;
-end;                                                                         
-\end{verbatim}
-\var{Data} points to the instance of the class with the method \var{Code}.
-
-\Errors
-No checking is done whether \var{Instance} is non-nil, or whether
-\var{PropInfo} describes a valid method property of \var{Instance}.
-Specifying an invalid property name in \var{PropName} will result in an
-\var{EPropertyError} exception
-\SeeAlso
-\seep{SetMethodProp}, \seef{GetOrdProp}, \seef{GetStrProp},
-\seef{GetFloatProp}, \seef{GetInt64Prop}, \seef{GetSetProp},
-\seef{GetObjectProp}, \seef{GetEnumProp}
-\end{function}
-
-\FPCexample{ex6}
-
-\begin{function}{GetObjectProp}
-\Declaration
-Function GetObjectProp(Instance: TObject; const PropName: string): TObject;\\
-Function GetObjectProp(Instance: TObject; const PropName: string; MinClass:TClass): TObject; \\
-Function GetObjectProp(Instance: TObject; PropInfo: PPropInfo; MinClass: TClass):
-TObject;\\
-\Description
-\var{GetObjectProp} returns the object which the property descroibed by
-\var{PropInfo} with name \var{Propname} points to for object \var{Instance}.
-
-If \var{MinClass} is specified, then if the object is not descendent of
-class \var{MinClass}, then \var{Nil} is returned.
-
-\Errors
-No checking is done whether \var{Instance} is non-nil, or whether
-\var{PropInfo} describes a valid method property of \var{Instance}. 
-Specifying an invalid property name in \var{PropName} will result in an
-\var{EPropertyError} exception.
-\SeeAlso
-\seep{SetMethodProp}, \seef{GetOrdProp}, \seef{GetStrProp},
-\seef{GetFloatProp}, \seef{GetInt64Prop}, \seef{GetSetProp},
-\seef{GetObjectProp}, \seef{GetEnumProp}
-\end{function}
-
-\FPCexample{ex5}
-
-\begin{function}{GetObjectPropClass}
-\Declaration
-Function GetObjectPropClass(Instance: TObject; const PropName: string): TClass;                                             
-\Description
-\var{GetObjectPropClass} returns the declared class of the property with name 
-\var{PropName}. This may not be the actual class of the property value.
-\Errors
-No checking is done whether \var{Instance} is non-nil.
-Specifying an invalid property name in \var{PropName} will result in an
-\var{EPropertyError} exception.
-\SeeAlso
-\seep{SetMethodProp}, \seef{GetOrdProp}, \seef{GetStrProp},
-\seef{GetFloatProp}, \seef{GetInt64Prop}
-\end{function}
-
-For an example, see \seef{GetObjectProp}.
-
-\begin{function}{GetOrdProp}
-\Declaration
-Function GetOrdProp(Instance : TObject;PropInfo : PPropInfo) : Longint;\\
-Function GetOrdProp(Instance: TObject;const PropName: string): Longint;
-\Description
-\var{GetOrdProp} returns the value of the ordinal property described by
-\var{PropInfo} or with name \var{PropName} for the object \var{Instance}. 
-The value is returned as a longint, which should be typecasted to the 
-needed type.
-
-Ordinal properties that can be retrieved include:
-\begin{description}
-\item[Integers and subranges of integers] The value of the integer will be
-returned.
-\item[Enumerated types and subranges of enumerated types] The ordinal value
-of the enumerated type will be returned.
-\item[Sets] If the base type of the set has less than 31 possible values.
-If a bit is set in the return value, then the corresponding element of the
-base ordinal class of the set type must be included in the set.
-\end{description}
-\Errors
-No checking is done whether \var{Instance} is non-nil, or whether
-\var{PropInfo} describes a valid ordinal property of \var{Instance}
-Specifying an invalid property name in \var{PropName} will result in an
-\var{EPropertyError} exception.
-\SeeAlso
-\seep{SetOrdProp}, \seef{GetStrProp}, \seef{GetFloatProp},
-\seef{GetInt64Prop},\seef{GetMethodProp}, \seef{GetSetProp},
-\seef{GetObjectProp}, \seef{GetEnumProp}
-\end{function}
-
-\FPCexample{ex1}
-
-\begin{function}{GetPropInfo}
-\Declaration
-Function GetPropInfo(AClass: TClass; const PropName: string; AKinds: TTypeKinds) : PPropInfo;\\
-Function GetPropInfo(AClass: TClass; const PropName: string): PPropInfo;\\
-Function GetPropInfo(Instance: TObject; const PropName: string): PPropInfo;\\
-Function GetPropInfo(Instance: TObject; const PropName: string; AKinds: TTypeKinds) : PPropInfo;\\
-Function GetPropInfo(TypeInfo: PTypeInfo;const PropName: string) : PPropInfo;\\
-Function GetPropInfo(TypeInfo: PTypeInfo;const PropName: string; AKinds : TTypeKinds) : PPropInfo;
-\Description
-\var{GetPropInfo} returns a pointer to the \var{TPropInfo} record for a the 
-\var{PropName} property of a class. The class to examine can be specified 
-in one of three ways:
-\begin{description}
-\item[Instance] An instance of the class.
-\item[AClass] A class pointer to the class.
-\item[TypeInfo] A pointer to the type information of the class.
-\end{description}
-In each of these three ways, if \var{AKinds} is specified, if the property 
-has \var{TypeKind} which is not included in \var{Akinds}, \var{Nil} will be
-returned.
-\Errors
-If the property \var{PropName} does not exist, \var{Nil} is returned.
-\SeeAlso
-\seep{GetPropInfos},\seef{GetPropList}
-\end{function}
-
-For an example, see most of the other functions.
-
-\begin{procedure}{GetPropInfos}
-\Declaration
-Procedure GetPropInfos(TypeInfo: PTypeInfo;PropList: PPropList);
-\Description
-\var{GetPropInfos} stores pointers to the property information of all published
-properties of a class with class info \var{TypeInfo} in the list pointed to by
-\var{Proplist}. The \var{PropList} pointer must point to a memory location that
-contains enough space to hold all properties of the class and its parent classes.
-\Errors
-No checks are done to see whether \var{PropList} points to a memory area that 
-is big enough to hold all pointers.
-\SeeAlso
-\seef{GetPropInfo},\seef{GetPropList}
-\end{procedure}
-
-\FPCexample{ex12}
-
-\begin{function}{GetPropList}
-\Declaration
-Function GetPropList(TypeInfo : PTypeInfo;
-                     TypeKinds : TTypeKinds; 
-                     PropList : PPropList) : Integer;
-\Description
-\var{GetPropList} stores pointers to property information of the class with class
-info \var{TypeInfo} for properties of kind \var{TypeKinds} in the list pointed to
-by \var{Proplist}. \var{PropList} must contain enough space to hold all properties.
-
-The function returns the number of pointers that matched the criteria and were stored
-in \var{PropList}.
-\Errors
-No checks are done to see whether \var{PropList} points to a memory area that is big enough
-to hold all pointers.
-\SeeAlso
-\seep{GetPropInfos}, \seef{GetPropInfo}
-\end{function}
-
-\FPCexample{ex13}
-
-\begin{function}{GetPropValue}
-\Declaration
-Function GetPropValue(Instance: TObject; const PropName: string): Variant;\\
-Function GetPropValue(Instance: TObject; const PropName: string; PreferStrings: Boolean): Variant;
-\Description
-Due to missing \var{Variant} support, \var{GetPropValue} is not yet implemented. 
-The declaration is provided for compatibility with Delphi.
-\Errors
-\SeeAlso
-\end{function}
-
-\begin{function}{GetSetProp}
-\Declaration
-Function GetSetProp(Instance: TObject; const PropInfo: PPropInfo; Brackets: Boolean):
-string;\\
-Function GetSetProp(Instance: TObject; const PropName: string): string;\\
-Function GetSetProp(Instance: TObject; const PropName: string; Brackets: Boolean): string;                 
-\Description
-\var{GetSetProp} returns the contents of a set property as a string.
-The property to be returned can be specified by it's name in \var{PropName}
-or by its property information in \var{PropInfo}.
-
-The returned set is a string representation of the elements in the set as
-returned by \seef{SetToString}. The \var{Brackets} option can be used to 
-enclose the string representation in square brackets.
-\Errors
-No checking is done whether \var{Instance} is non-nil, or whether
-\var{PropInfo} describes a valid ordinal property of \var{Instance}
-Specifying an invalid property name in \var{PropName} will result in an
-\var{EPropertyError} exception.                                                 
-\SeeAlso
-\seep{SetSetProp}, \seef{GetStrProp}, \seef{GetFloatProp},
-\seef{GetInt64Prop},\seef{GetMethodProp}
-\end{function}
-
-\FPCexample{ex7}
-
-\begin{function}{GetStrProp}
-\Declaration
-Function GetStrProp(Instance : TObject;
-                    PropInfo : PPropInfo) : Ansistring;\\
-Function GetStrProp(Instance: TObject; 
-                    const PropName: string): string;
-\Description
-\var{GetStrProp} returns the value of the string property described by
-\var{PropInfo} or with name \var{PropName} for object \var{Instance}. 
-\Errors
-No checking is done whether \var{Instance} is non-nil, or whether
-\var{PropInfo} describes a valid string property of \var{Instance}.
-Specifying an invalid property name in \var{PropName} will result in an
-\var{EPropertyError} exception.
-\SeeAlso
-\seep{SetStrProp}, \seef{GetOrdProp}, \seef{GetFloatProp},
-\seef{GetInt64Prop},\seef{GetMethodProp}
-\end{function}
-
-\FPCexample{ex3}
-
-\begin{function}{GetTypeData}
-\Declaration
-Function GetTypeData(TypeInfo : PTypeInfo) : PTypeData;
-\Description
-\var{GetTypeData} returns a pointer to the \var{TTypeData} record that
-follows after the \var{TTypeInfo} record pointed to by \var{TypeInfo}.
-It essentially skips the \var{Kind} and \var{Name} fields in the 
-\var{TTypeInfo} record.
-\Errors
-None.
-\SeeAlso
-\end{function}
-
-\begin{function}{GetVariantProp}
-\Declaration
-Function GetVariantProp(Instance : TObject;PropInfo : PPropInfo): Variant;
-\Description
-Due to mising Variant support, the \var{GetVariantProp} function is not 
-yet implemented. Provided for Delphi compatibility only.
-\Errors
-\SeeAlso
-\seep{SetVariantProp}
-\end{function}
-
-\begin{function}{IsPublishedProp}
-\Declaration
-Function IsPublishedProp(AClass: TClass; const PropName: string): Boolean;\\
-Function IsPublishedProp(Instance: TObject; const PropName: string): Boolean;                              
-\Description
-\var{IsPublishedProp} returns true if a class has a published property with
-name \var{PropName}. The class can be specfied in one of two ways:
-\begin{description}
-\item[AClass] A class pointer to the class.
-\item[Instance] An instance of the class.
-\end{description}
-\Errors
-No checks are done to ensure \var{Instance} or \var{AClass} are valid
-pointers. Specifying an invalid property name in \var{PropName} will result
-in an \var{EPropertyError} exception.                                                 
-\SeeAlso
-\seef{IsStoredProp}, \seef{PropIsType}
-\end{function}
-
-\FPCexample{ex10}
-
-\begin{function}{IsStoredProp}
-\Declaration
-Function IsStoredProp(Instance : TObject;PropInfo : PPropInfo) : Boolean;\\
-Function IsStoredProp(Instance: TObject; const PropName: string): Boolean; 
-\Description
-\var{IsStoredProp} returns \var{True} if the \var{Stored} modifier evaluates
-to \var{True} for the property described by \var{PropInfo} or with name
-\var{PropName} for object \var{Instance}. 
-It returns \var{False} otherwise. If the function returns
-\var{True}, this indicates that the property should be written when
-streaming the object \var{Instance}.
-
-If there was no \var{stored} modifier in the declaration of the property, 
-\var{True} will be returned. 
-\Errors
-No checking is done whether \var{Instance} is non-nil, or whether
-\var{PropInfo} describes a valid property of \var{Instance}.
-Specifying an invalid property name in \var{PropName} will result in an
-\var{EPropertyError} exception.                                                 
-\SeeAlso
-\seef{IsPublishedProp}, \seef{PropIsType}
-\end{function}
-
-\FPCexample{ex11}
-
-\begin{function}{PropIsType}
-\Declaration
-Function PropIsType(AClass: TClass; 
-                    const PropName: string; TypeKind: TTypeKind): Boolean;\\
-Function PropIsType(Instance: TObject; 
-                    const PropName: string; TypeKind: TTypeKind): Boolean;              
-\Description
-\var{PropIsType} returns \var{True} if the property with name \var{PropName}
-has type \var{TypeKind}. It returns \var{False} otherwise. The class to be
-examined can be specified in one of two ways:
-\begin{description}
-\item[AClass] A class pointer. 
-\item[Instance] An instance of the class.
-\end{description}
-\Errors
-No checks are done to ensure \var{Instance} or \var{AClass} are valid
-pointers.Specifying an invalid property name in \var{PropName} will result
-in an \var{EPropertyError} exception.                                                 
-\SeeAlso
-\seef{IsPublishedProp}, \seef{IsStoredProp}, \seef{PropType}
-\end{function}
-
-\FPCexample{ex16}
-
-\begin{function}{PropType}
-\Declaration
-Function PropType(AClass: TClass; const PropName: string): TTypeKind;\\
-Function PropType(Instance: TObject; const PropName: string): TTypeKind;
-\Description
-\var{Proptype} returns the type of the property \var{PropName} for a class.
-The class to be examined can be specified in one of 2 ways:
-\begin{description}
-\item[AClass] A class pointer. 
-\item[Instance] An instance of the class.
-\end{description}
-\Errors
-No checks are done to ensure \var{Instance} or \var{AClass} are valid
-pointers. Specifying an invalid property name in \var{PropName} will result
-in an \var{EPropertyError} exception.
-\SeeAlso
-\seef{IsPublishedProp}, \seef{IsStoredProp}, \seef{PropIsType}
-\end{function}
-
-\FPCexample{ex17}
-
-\begin{procedure}{SetEnumProp}
-\Declaration
-Procedure SetEnumProp(Instance: TObject; const PropInfo: PPropInfo;
-                      const Value: string);\\
-Procedure SetEnumProp(Instance: TObject; const PropName: string;
-                      const Value: string);                      
-\Description
-\var{SetEnumProp} sets the property described by \var{PropInfo} or with name
-\var{PropName} to \var{Value}. \var{Value} must be a string with the name
-of the enumerate value, i.e. it can be used as an argument to 
-\seef{GetEnumValue}.
-\Errors
-No checks are done to ensure \var{Instance} or \var{PropInfo} are valid
-pointers. Specifying an invalid property name in \var{PropName} will result
-in an \var{EPropertyError} exception.                                           
-\SeeAlso
-\seef{GetEnumProp}, \seep{SetStrProp}, \seep{SetFloatProp},
-\seep{SetInt64Prop},\seep{SetMethodProp}.
-\end{procedure}
-
-For an example, see \seef{GetEnumProp}.
-
-\begin{procedure}{SetFloatProp}
-\Declaration
-Procedure SetFloatProp(Instance : TObject;
-                       PropInfo : PPropInfo;
-                       Value : Extended);\\
-Procedure SetFloatProp(Instance: TObject; 
-                       const PropName: string; 
-                       Value: Extended);
-\Description
-\var{SetFloatProp} assigns \var{Value} to the property described by
-\var{PropInfo} or with name \var{Propname} for the object \var{Instance}.
-\Errors
-No checking is done whether \var{Instance} is non-nil, or whether
-\var{PropInfo} describes a valid float property of \var{Instance}.
-Specifying an invalid property name in \var{PropName} will result in an
-\var{EPropertyError} exception.
-\SeeAlso
-\seef{GetFloatProp}, \seep{SetOrdProp}, \seep{SetStrProp},
-\seep{SetInt64Prop},\seep{SetMethodProp}
-\end{procedure}
-
-For an example, see \seef{GetFloatProp}.
-
-
-\begin{procedure}{SetInt64Prop}
-\Declaration
-Procedure SetInt64Prop(Instance: TObject; PropInfo: PPropInfo; const Value: Int64);\\
-Procedure SetInt64Prop(Instance: TObject; const PropName: string; const Value: Int64);
-\Description
-\var{SetInt64Prop} assigns \var{Value} to the property of type
-\var{Int64} that is described by \var{PropInfo} or with name \var{Propname} 
-for the object \var{Instance}.
-\Errors
-No checking is done whether \var{Instance} is non-nil, or whether
-\var{PropInfo} describes a valid \var{Int64} property of \var{Instance}.
-Specifying an invalid property name in \var{PropName} will result in an
-\var{EPropertyError} exception.
-\SeeAlso
-\seef{GetInt64Prop}, \seef{GetMethodProp}, \seep{SetOrdProp}, \seep{SetStrProp},
-\seep{SetFloatProp}
-\end{procedure}
-
-For an example, see \seef{GetInt64Prop}.
-
-
-\begin{procedure}{SetMethodProp}
-\Declaration
-Procedure SetMethodProp(Instance : TObject;PropInfo : PPropInfo; const Value :
-TMethod);\\
-Procedure SetMethodProp(Instance: TObject; const PropName: string; const Value: TMethod);
-\Description
-\var{SetMethodProp} assigns \var{Value} to the method the property described 
-by \var{PropInfo} or with name \var{Propname} for object \var{Instance}.
-
-The type \var{TMethod} of the \var{Value} parameter is defined in the
-\file{SysUtils} unit as:
-\begin{verbatim}
-TMethod = packed record
-  Code, Data: Pointer;
-end;                                                                         
-\end{verbatim}
-\var{Data} should point to the instance of the class with the method \var{Code}.
-
-\Errors
-No checking is done whether \var{Instance} is non-nil, or whether
-\var{PropInfo} describes a valid method property of \var{Instance}.
-Specifying an invalid property name in \var{PropName} will result in an
-\var{EPropertyError} exception.
-\SeeAlso
-\seef{GetMethodProp}, \seep{SetOrdProp}, \seep{SetStrProp},
-\seep{SetFloatProp}, \seep{SetInt64Prop}
-\end{procedure}
-
-For an example, see \seef{GetMethodProp}.
-
-
-\begin{procedure}{SetObjectProp}
-\Declaration
-Procedure SetObjectProp(Instance: TObject; 
-                        PropInfo: PPropInfo; Value: TObject);\\
-Procedure SetObjectProp(Instance: TObject; 
-                        const PropName: string; Value: TObject);                        
-\Description
-\var{SetObjectProp} assigns \var{Value} to the the object property described by
-\var{PropInfo} or with name \var{Propname} for the object \var{Instance}. 
-\Errors
-No checking is done whether \var{Instance} is non-nil, or whether
-\var{PropInfo} describes a valid method property of \var{Instance}.
-Specifying an invalid property name in \var{PropName} will result in an
-\var{EPropertyError} exception.
-\SeeAlso
-\seef{GetObjectProp}, \seep{SetOrdProp}, \seep{SetStrProp},
-\seep{SetFloatProp}, \seep{SetInt64Prop}, \seep{SetMethodProp}
-\end{procedure}
-
-For an example, see \seef{GetObjectProp}.
-
-\begin{procedure}{SetOrdProp}
-\Declaration
-Procedure SetOrdProp(Instance : TObject; PropInfo : PPropInfo; 
-                     Value : Longint);\\
-Procedure SetOrdProp(Instance: TObject; const PropName: string;
-                     Value: Longint);
-\Description
-\var{SetOrdProp} assigns \var{Value} to the the ordinal property described by 
-\var{PropInfo} or with name \var{Propname} for the object \var{Instance}. 
-
-Ordinal properties that can be set include:
-\begin{description}
-\item[Integers and subranges of integers] The actual value of the integer must be 
-passed.
-\item[Enumerated types and subranges of enumerated types] The ordinal value
-of the enumerated type must be passed.
-\item[Subrange types] of integers or enumerated types. Here the ordinal
-value must be passed.
-\item[Sets] If the base type of the set has less than 31 possible values.
-For each possible value; the corresponding bit of \var{Value} must be set.
-\end{description}
-\Errors
-No checking is done whether \var{Instance} is non-nil, or whether
-\var{PropInfo} describes a valid ordinal property of \var{Instance}. 
-No range checking is performed.
-Specifying an invalid property name in \var{PropName} will result in an
-\var{EPropertyError} exception.
-\SeeAlso
-\seef{GetOrdProp}, \seep{SetStrProp}, \seep{SetFloatProp},
-\seep{SetInt64Prop},\seep{SetMethodProp}
-\end{procedure}
-
-
-For an example, see \seef{GetOrdProp}.
-
-
-\begin{procedure}{SetPropValue}
-\Declaration
-Procedure SetPropValue(Instance: TObject; 
-                       const PropName: string; const Value: Variant);                   
-\Description
-Due to missing Variant support, this function is not yet implemented;
-it is provided for Delphi compatibility only.
-\Errors
-\SeeAlso
-\end{procedure}
-
-\begin{procedure}{SetSetProp}
-\Declaration
-Procedure SetSetProp(Instance: TObject; 
-                     const PropInfo: PPropInfo; const Value: string);\\
-Procedure SetSetProp(Instance: TObject;
-                     const PropName: string; const Value: string);                      
-\Description
-\var{SetSetProp} sets the property specified by \var{PropInfo} or
-\var{PropName} for object \var{Instance} to \var{Value}. \var{Value} is a
-string which contains a comma-separated list of values, each value being a
-string-representation of the enumerated value that should be included in
-the set. The value should be accepted by the \seef{StringToSet} function.
-
-The value can be formed using the \seef{SetToString} function.
-\Errors
-No checking is done whether \var{Instance} is non-nil, or whether
-\var{PropInfo} describes a valid ordinal property of \var{Instance}.
-No range checking is performed.
-Specifying an invalid property name in \var{PropName} will result in an
-\var{EPropertyError} exception.                                                 
-\SeeAlso
-\seef{GetSetProp}, \seep{SetOrdProp}, \seep{SetStrProp}, \seep{SetFloatProp},
-\seep{SetInt64Prop},\seep{SetMethodProp}, \seef{SetToString},
-\seef{StringToSet}
-\end{procedure}
-
-For an example, see \seef{GetSetProp}.
-
-\begin{procedure}{SetStrProp}
-\Declaration
-procedure SetStrProp(Instance : TObject; PropInfo : PPropInfo; 
-                     const Value : Ansistring);\\
-Procedure SetStrProp(Instance: TObject; const PropName: string; 
-                     const Value: AnsiString);
-\Description
-\var{SetStrProp} assigns \var{Value} to the string property described by
-\var{PropInfo} or with name \var{Propname} for object \var{Instance}. 
-
-\Errors
-No checking is done whether \var{Instance} is non-nil, or whether
-\var{PropInfo} describes a valid string property of \var{Instance}.
-Specifying an invalid property name in \var{PropName} will result in an
-\var{EPropertyError} exception.
-\SeeAlso
-\seef{GetStrProp}, \seep{SetOrdProp}, \seep{SetFloatProp},
-\seep{SetInt64Prop},\seep{SetMethodProp}
-\end{procedure}
-
-For an example, see \seef{GetStrProp}
-
-\begin{function}{SetToString}
-\Declaration
-function SetToString(PropInfo: PPropInfo; 
-                     Value: Integer) : String;\\
-function SetToString(PropInfo: PPropInfo; 
-                     Value: Integer; Brackets: Boolean) : String;
-\Description
-\var{SetToString} takes an integer representation of a set (as received e.g.
-by \var{GetOrdProp}) and turns it into a string representing the elements in
-the set, based on the type information found in the \var{PropInfo} property
-information. By default, the string representation is not surrounded by
-square brackets. Setting the \var{Brackets} parameter to \var{True} will 
-surround the string representation with brackets.
-
-The function returns the string representation of the set.
-\Errors
-No checking is done to see whether \var{PropInfo} points to valid property
-information.
-\SeeAlso
-\seef{GetEnumName}, \seef{GetEnumValue}, \seef{StringToSet}
-\end{function}
-
-\FPCexample{ex18}
-
-\begin{procedure}{SetVariantProp}
-\Declaration
-Procedure SetVariantProp(Instance : TObject;
-                         PropInfo : PPropInfo;
-                         Const Value: Variant);\\
-Procedure SetVariantProp(Instance: TObject; 
-                         const PropName: string; 
-                         const Value: Variant);                 
-\Description
-Due to missing Variant support, this function is not yet implemented. 
-Provided for Delphi compatibility only.
-\Errors
-\SeeAlso
-\end{procedure}
-
-
-\begin{function}{StringToSet}
-\Declaration
-function StringToSet(PropInfo: PPropInfo; const Value: string): Integer;
-\Description
-\var{StringToSet} converts the string representation of a set in \var{Value}
-to a integer representation of the set, using the property information found
-in \var{PropInfo}. This property information should point to the property
-information of a set property. The function returns the integer
-representation of the set. (i.e, the set value, typecast to an integer)
-
-The string representation can be surrounded with square brackets, and must 
-consist of the names of the elements of the base type of the set. The base
-type of the set should be an enumerated type. The elements should be
-separated by commas, and may be surrounded by spaces.
-each of the names will be fed to the \seef{GetEnumValue} function.
-\Errors
-No checking is done to see whether \var{PropInfo} points to valid property
-information. If a wrong name is given for an enumerated value, then an
-\var{EPropertyError} will be raised.
-\SeeAlso
-\seef{GetEnumName}, \seef{GetEnumValue}, \seef{SetToString}
-\end{function}
-
-For an example, see \seef{SetToString}.

docs/video.tex

@@ -1,700 +0,0 @@
-%
-%   $Id$
-%   This file is part of the FPC documentation.
-%   Copyright (C) 1997, by Michael Van Canneyt
-%
-%   The FPC documentation is free text; you can redistribute it and/or
-%   modify it under the terms of the GNU Library General Public License as
-%   published by the Free Software Foundation; either version 2 of the
-%   License, or (at your option) any later version.
-%
-%   The FPC Documentation is distributed in the hope that it will be useful,
-%   but WITHOUT ANY WARRANTY; without even the implied warranty of
-%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-%   Library General Public License for more details.
-%
-%   You should have received a copy of the GNU Library General Public
-%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
-%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-%   Boston, MA 02111-1307, USA.
-%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% The Video unit
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\chapter{The VIDEO unit}
-\FPCexampledir{videoex}
-
-The \file{Video} unit implements a screen access layer which is system
-independent. It can be used to write on the screen in a system-independent
-way, which should be optimal on all platforms for which the unit is
-implemented.
-
-The working of the \file{Video} is simple: After calling \seep{InitVideo},
-the array \var{VideoBuf} contains a representation of the video screen of
-size \var{ScreenWidth*ScreenHeight}, going from left to right and top to
-bottom when walking the array elements: \var{VideoBuf[0]} contains the 
-character and color code of the top-left character on the screen.
-\var{VideoBuf[ScreenWidth]} contains the data for the character in the
-first column of the second row on the screen, and so on.
-
-To write to the 'screen', the text to be written should be written to the
-\var{VideoBuf} array. Calling \seep{UpdateScreen} will then cp the text to
-the screen in the most optimal way. (an example can be found further on).
-
-The color attribute is a combination of the foreground and background color,
-plus the blink bit. The bits describe the various color combinations:
-\begin{description}
-\item[bits 0-3] The foreground color. Can be set using all color constants. 
-\item[bits 4-6] The background color. Can be set using a subset of the
-color constants.
-\item[bit 7] The blinking bit. If this bit is set, the character will appear
-blinking.
-\end{description}
-Each possible color has a constant associated with it, see page
-\pageref{vidcolorconst} for a list of constants.
-
-The contents of the \var{VideoBuf} array may be modified: This is 'writing'
-to the screen. As soon as everything that needs to be written in the array
-is in the \var{VideoBuf} array, calling \var{UpdateScreen} will copy the
-contents of the array screen to the screen, in a manner that is as efficient
-as possible.
-
-The updating of the screen can be prohibited to optimize performance; To
-this end, the \seep{LockScreenUpdate} function can be used: This will
-increment an internal counter. As long as the counter differs from zero,
-calling \seep{UpdateScreen} will not do anything. The counter can be
-lowered with \seep{UnlockScreenUpdate}. When it reaches zero, the next call
-to \seep{UpdateScreen} will actually update the screen. This is useful when
-having nested procedures that do a lot of screen writing.
-
-The video unit also presents an interface for custom screen drivers, thus
-it is possible to override the default screen driver with a custom screen 
-driver, see the \seef{SetVideoDriver} call. The current video driver can
-be retrieved using the \seep{GetVideoDriver} call.
-
-\begin{remark}
-The video unit should {\em not} be used together with the \file{crt} unit.
-Doing so will result in very strange behaviour, possibly program crashes.
-\end{remark}
-
-\section{Constants, Type and variables }
-
-\subsection{Constants}
-\label{vidcolorconst}
-The following constants describe colors that can be used as 
-foreground and background colors.
-\begin{verbatim}
-Black         = 0;
-Blue          = 1;
-Green         = 2;
-Cyan          = 3;
-Red           = 4;
-Magenta       = 5;
-Brown         = 6;
-LightGray     = 7;
-\end{verbatim}
-The following color constants can be used as foreground colors only:
-\begin{verbatim}
-DarkGray      = 8;
-LightBlue     = 9;
-LightGreen    = 10;
-LightCyan     = 11;
-LightRed      = 12;
-LightMagenta  = 13;
-Yellow        = 14;
-White         = 15;
-\end{verbatim}
-The foreground and background color can be combined to a color attribute
-with the following code:
-\begin{verbatim}
-Attr:=ForeGroundColor + (BackGroundColor shl 4);
-\end{verbatim}
-The color attribute can be logically or-ed with the blink attribute to
-produce a blinking character:
-\begin{verbatim}
-Blink         = 128;
-\end{verbatim}
-But not all drivers may support this.
-
-The following constants describe the capabilities of a certain video mode:
-\begin{verbatim}
-cpUnderLine     = $0001;
-cpBlink         = $0002;
-cpColor         = $0004;
-cpChangeFont    = $0008;
-cpChangeMode    = $0010;
-cpChangeCursor  = $0020;
-\end{verbatim}
-The following constants describe the various supported cursor modes:
-\begin{verbatim}
-crHidden        = 0;
-crUnderLine     = 1;
-crBlock         = 2;
-crHalfBlock     = 3;
-\end{verbatim}
-When a video function needs to report an error condition, the following
-constants are used:
-\begin{verbatim}
-vioOK              = 0;
-errVioBase         = 1000;
-errVioInit         = errVioBase + 1; { Initialization error}
-errVioNotSupported = errVioBase + 2; { Unsupported function }
-errVioNoSuchMode   = errVioBase + 3; { No such video mode }
-\end{verbatim}
-The following constants can be read to get some information about the
-current screen:
-\begin{verbatim}
-ScreenWidth     : Word = 0;  { Width of the screen, in characters  }
-ScreenHeight    : Word = 0;  { Height of the screen, in characters }
-LowAscii        : Boolean = true;
-NoExtendedFrame : Boolean = false;
-FVMaxWidth      = 132; 
-\end{verbatim}
-The error-handling code uses the following constants:
-\begin{verbatim}
-errOk              = 0;
-ErrorCode: Longint = ErrOK;
-ErrorInfo: Pointer = nil;
-ErrorHandler: TErrorHandler = DefaultErrorHandler;
-\end{verbatim}
-The \var{ErrorHandler} variable can be set to a custom-error handling
-function. It is set by default to the \seep{DefaultErrorHandler} function.
-
-\subsection{Types}
-The \var{TVideoMode} record describes a videomode. Its fields are
-self-explaining: \var{Col,Row} describe the number of columns and 
-rows on the screen for this mode. \var{Color} is \var{True} if this mode
-supports colors, or \var{False} if not.
-\begin{verbatim}
-  PVideoMode = ^TVideoMode;
-  TVideoMode = record
-    Col,Row : Word;
-    Color   : Boolean;
-  end;
-\end{verbatim}
-\var{TVideoCell} describes one character on the screen. One of the bytes 
-contains the color attribute with which the character is drawn on the screen,
-and the other byte contains the ASCII code of the character to be drawn. The
-exact position of the different bytes in the record is operating system specific.
-On most little-endian systems, the high byte represents the color attribute,
-while the low-byte represents the ASCII code of the character to be drawn.
-\begin{verbatim}
-TVideoCell = Word;
-PVideoCell = ^TVideoCell;
-\end{verbatim}
-The \var{TVideoBuf} and \var{PVideoBuf} are two types used to represent the
-screen.
-\begin{verbatim}
-TVideoBuf = array[0..32759] of TVideoCell;
-PVideoBuf = ^TVideoBuf;
-\end{verbatim}
-The following type is used when reporting error conditions:
-\begin{verbatim}
-TErrorHandlerReturnValue = (errRetry, errAbort, errContinue);
-\end{verbatim}
-Here, \var{errRetry} means retry the operation, \var{errAbort}
-abort and return error code and \var{errContinue} means abort
-without returning an errorcode.
-
-The \var{TErrorHandler} function is used to register an own error
-handling function. It should be used when installing a custom error
-handling function, and must return one of the above values.
-\begin{verbatim}
-TErrorHandler = 
-  function (Code: Longint; Info: Pointer): TErrorHandlerReturnValue;
-\end{verbatim}
-\var{Code} should contain the error code for the error condition, 
-and the \var{Info} parameter may contain any data type specific to 
-the error code passed to the function.
-
-The \var{TVideoDriver} record can be used to install a custom video
-driver, with the \seef{SetVideoDriver} call:
-\begin{verbatim}
-TVideoDriver = Record
-  InitDriver        : Procedure;
-  DoneDriver        : Procedure;
-  UpdateScreen      : Procedure(Force : Boolean);
-  ClearScreen       : Procedure;
-  SetVideoMode      : Function (Const Mode : TVideoMode) : Boolean;
-  GetVideoModeCount : Function : Word;
-  GetVideoModeData  : Function(Index : Word; Var Data : TVideoMode) : Boolean;
-  SetCursorPos      : procedure (NewCursorX, NewCursorY: Word);
-  GetCursorType     : function : Word;
-  SetCursorType     : procedure (NewType: Word);
-  GetCapabilities   : Function : Word;
-end;
-\end{verbatim}
-
-\subsection{Variables}
-The following variables contain information about the current screen
-status:
-\begin{verbatim}
-ScreenColor      : Boolean;
-CursorX, CursorY : Word;
-\end{verbatim}
-\var{ScreenColor} indicates whether the current screen supports colors.
-\var{CursorX,CursorY} contain the current cursor position.
-
-The following variable forms the heart of the \file{Video} unit: The
-\var{VideoBuf} array represents the physical screen. Writing to this
-array and calling \seep{UpdateScreen} will write the actual characters
-to the screen. 
-\begin{verbatim}
-VideoBuf     : PVideoBuf;
-OldVideoBuf  : PVideoBuf;
-VideoBufSize : Longint;
-\end{verbatim}
-The \var{OldVideoBuf} contains the state of the video screen after the last
-screen update. The \seep{UpdateScreen} function uses this array to decide
-which characters on screen should be updated, and which not. 
-
-Note that the \var{OldVideoBuf} array may be ignored by some drivers, so
-it should not be used. The Array is in the interface section of the video
-unit mainly so drivers that need it can make use of it. 
-
-\section{Functions and Procedures}
-
-The examples in this section make use of the unit \file{vidutil}, which 
-contains the \var{TextOut} function. This function writes a text to the
-screen at a given location. It looks as follows:
-
-\FPCexample{vidutil}
-
-\begin{procedure}{ClearScreen}
-\Declaration
-procedure ClearScreen; 
-\Description
-\var{ClearScreen} clears the entire screen, and calls \seep{UpdateScreen}
-after that. This is done by writing spaces to all character cells of the
-video buffer in the default color (lightgray on black, color attribute \$07).
-\Errors
-None.
-\SeeAlso
-\seep{InitVideo}, \seep{UpdateScreen}
-\end{procedure}
-
-\FPCexample{ex3}
-
-\begin{procedure}{DefaultErrorHandler}
-\Declaration
-function  DefaultErrorHandler(AErrorCode: Longint; AErrorInfo: Pointer): TErrorHandlerReturnValue; 
-\Description
-\var{DefaultErrorHandler} is the default error handler used by the video
-driver. It simply sets the error code \var{AErrorCode} and \var{AErrorInfo} 
-in the global variables \var{ErrorCode} and \var{ErrorInfo} and returns 
-\var{errContinue}.
-\Errors
-None.
-\SeeAlso
-\end{procedure}
-
-\begin{procedure}{DoneVideo}
-\Declaration
-procedure DoneVideo; 
-\Description
-\var{DoneVideo} disables the Video driver if the video driver is active. If
-the videodriver was already disabled or not yet initialized, it does
-nothing. Disabling the driver means it will clean up any allocated
-resources, possibly restore the screen in the state it was before
-\var{InitVideo} was called. Particularly, the \var{VideoBuf} and
-\var{OldVideoBuf} arrays are no longer valid after a call to 
-\var{DoneVideo}.
-
-The \var{DoneVideo} should always be called if \var{InitVideo} was called.
-Failing to do so may leave the screen in an unusable state after the program
-exits.
-\Errors
-Normally none. If the driver reports an error, this is done through the
-\var{ErrorCode} variable.
-\SeeAlso
-\seep{InitVideo}
-\end{procedure}
-
-For an example, see most other functions.
-
-\begin{function}{GetCapabilities}
-\Declaration
-function GetCapabilities: Word; 
-\Description
-\var{GetCapabilities} returns the capabilities of the current driver.
-It is an or-ed combination of the following constants:
-\begin{description}
-\item[cpUnderLine] The driver supports underlined characters.
-\item[cpBlink] The driver supports blinking characters.
-\item[cpColor] The driver supports colors.
-\item[cpChangeFont] The driver supports the setting of a screen font.
-Note, however, that a font setting API is not supported by the video unit.
-\item[cpChangeMode] The driver supports the setting of screen modes. 
-\item[cpChangeCursor] The driver supports changing the cursor shape.
-\end{description}
-Note that the video driver should not yet be initialized to use this
-function. It is a property of the driver.
-\Errors
-None.
-\SeeAlso
-\seef{GetCursorType}, \seep{GetVideoDriver}
-\end{function}
-
-\FPCexample{ex4}
-
-\begin{function}{GetCursorType}
-\Declaration
-function GetCursorType: Word; 
-\Description
-\var{GetCursorType} returns the current cursor type. It is one of the
-following values: 
-\begin{description}
-\item[crHidden] The cursor is currently hidden.
-\item[crUnderLine] The cursor is currently the underline character.
-\item[crBlock] The cursor is currently the block character.
-\item[crHalfBlock] The cursur is currently a block with height of half the
-character cell height.
-\end{description}
-Note that not all drivers support all types of cursors.
-\Errors
-None.
-\SeeAlso
-\seep{SetCursorType}, \seef{GetCapabilities}
-\end{function}
-
-\FPCexample{ex5}
-
-\begin{function}{GetLockScreenCount}
-\Declaration
-Function GetLockScreenCount : integer;
-\Description
-\var{GetLockScreenCount} returns the current lock level. When the lock
-level is zero, a call to \seep{UpdateScreen} will actually update the
-screen.
-\Errors
-None.
-\SeeAlso
-\seep{LockScreenUpdate}, \seep{UnlockScreenUpdate}, \seep{UpdateScreen}
-\end{function}
-
-\FPCexample{ex6}
-
-\begin{procedure}{GetVideoDriver}
-\Declaration
-Procedure GetVideoDriver (Var Driver : TVideoDriver);
-\Declaration
-\var{GetVideoDriver} retrieves the current videodriver and returns it in
-\var{Driver}. This can be used to chain video drivers.
-\Errors
-None.
-\SeeAlso
-\seef{SetVideoDriver}
-\end{procedure}
-
-For an example, see the section on writing a custom video driver.
-
-\begin{procedure}{GetVideoMode}
-\Declaration
-procedure GetVideoMode(var Mode: TVideoMode); 
-\Description
-\var{GetVideoMode} returns the settings of the currently active video mode.
-The \var{row,col} fields indicate the dimensions of the current video mode,
-and \var{Color} is true if the current video supports colors.
-\Errors
-None.
-\SeeAlso
-\seef{SetVideoMode}, \seef{GetVideoModeData}
-\end{procedure}
-
-\FPCexample{ex7}
-
-\begin{function}{GetVideoModeCount}
-\Declaration
-Function GetVideoModeCount : Word;
-\Description
-\var{GetVideoModeCount} returns the number of video modes that the current
-driver supports. If the driver does not support switching of modes, then 1
-is returned.
-
-This function can be used in conjunction with the \seef{GetVideoModeData}
-function to retrieve data for the supported video modes.
-\Errors
-None.
-\SeeAlso
-\seef{GetVideoModeData}, \seep{GetVideoMode}
-\end{function}
-
-\FPCexample{ex8}
-
-\begin{function}{GetVideoModeData}
-\Declaration
-Function GetVideoModeData(Index : Word; Var Data: TVideoMode) : Boolean;  
-\Description
-\var{GetVideoModeData} returns the characteristics of the \var{Index}-th
-video mode in \var{Data}. \var{Index} is zero based, and has a maximum value of
-\var{GetVideoModeCount-1}. If the current driver does not support setting of
-modes (\var{GetVideoModeCount=1}) and \var{Index} is zero, the current mode 
-is returned.
-
-The function returns \var{True} if the mode data was retrieved succesfully,
-\var{False} otherwise.
-\Errors
-In case \var{Index} has a wrong value, \var{False} is returned.
-\SeeAlso
-\seef{GetVideoModeCount}, \seef{SetVideoMode}, \seep{GetVideoMode}
-\end{function}
-
-For an example, see \seef{GetVideoModeCount}.
-
-\begin{procedure}{InitVideo}
-\Declaration
-procedure InitVideo; 
-\Description
-\var{InitVideo} Initializes the video subsystem. If the video system was
-already initialized, it does nothing. 
-After the driver has been initialized, the \var{VideoBuf} and \var{OldVideoBuf} 
-pointers are initialized, based on the \var{ScreenWidth} and
-\var{ScreenHeight} variables. When this is done, the screen is cleared.
-\Errors
-if the driver fails to initialize, the \var{ErrorCode} variable is set.
-\SeeAlso
-\seep{DoneVideo}
-\end{procedure}
-
-For an example, see most other functions.
-
-\begin{procedure}{LockScreenUpdate}
-\Declaration
-Procedure LockScreenUpdate;
-\Description
-\var{LockScreenUpdate} increments the screen update lock count with one.
-As long as the screen update lock count is not zero, \seep{UpdateScreen}
-will not actually update the screen.
-
-This function can be used to optimize screen updating: If a lot of writing
-on the screen needs to be done (by possibly unknown functions), calling
-\var{LockScreenUpdate} before the drawing, and \seep{UnlockScreenUpdate}
-after the drawing, followed by a \seep{UpdateScreen} call, all writing will
-be shown on screen at once.
-\Errors
-None.
-\SeeAlso
-\seep{UpdateScreen}, \seep{UnlockScreenUpdate}, \seef{GetLockScreenCount}
-\end{procedure}
-
-For an example, see \seef{GetLockScreenCount}.
-
-\begin{procedure}{SetCursorPos}
-\Declaration
-procedure SetCursorPos(NewCursorX, NewCursorY: Word); 
-\Description
-\var{SetCursorPos} positions the cursor on the given position: Column 
-\var{NewCursorX} and row \var{NewCursorY}. The origin of the screen is the
-upper left corner, and has coordinates \var{(0,0)}.
-
-The current position is stored in the \var{CursorX} and \var{CursorY}
-variables.
-\Errors
-None.
-\SeeAlso
-\seep{SetCursorType}
-\end{procedure}
-
-\FPCexample{ex2}
-
-\begin{procedure}{SetCursorType}
-\Declaration
-procedure SetCursorType(NewType: Word); 
-\Description
-\var{SetCursorType} sets the cursor to the type specified in \var{NewType}.
-\begin{description}
-\item[crHidden] the cursor is not visible.
-\item[crUnderLine] the cursor is a small underline character (usually 
-denoting insert mode).
-\item[crBlock] the cursor is a block the size of a screen cell (usually
-denoting overwrite mode).
-\item[crHalfBlock] the cursor is a block half the size of a screen cell.
-\end{description}
-\Errors
-None.
-\SeeAlso
-\seep{SetCursorPos}
-\end{procedure}
-
-\begin{function}{SetVideoDriver}
-\Declaration
-Function SetVideoDriver (Const Driver : TVideoDriver) : Boolean;
-\Description
-\var{SetVideoDriver} sets the videodriver to be used to \var{Driver}. If
-the current videodriver is initialized (after a call to \var{InitVideo})
-then it does nothing and returns \var{False}.
-
-A new driver can only be installed if the previous driver was not yet
-activated (i.e. before a call to \seep{InitVideo}) or after it was
-deactivated (i.e after a call to \var{DoneVideo}).
-
-For more information about installing a videodriver, see \sees{viddriver}.
-\Errors
-If the current driver is initialized, then \var{False} is returned.
-\SeeAlso
-The example video driver in \sees{viddriver}
-\end{function}
-
-For an example, see the section on writing a custom video driver.
-
-\begin{function}{SetVideoMode}
-\Declaration
-Function SetVideoMode(Mode: TVideoMode) : Boolean;
-\Description
-\var{SetVideoMode} sets the video mode to the mode specified in \var{Mode}:
-\begin{verbatim}
-  TVideoMode = record
-    Col,Row : Word;
-    Color   : Boolean;
-  end;
-\end{verbatim}
-If the call was succesful, then the screen will have \var{Col} columns and
-\var{Row} rows, and will be displaying in color if \var{Color} is
-\var{True}. 
-
-The function returns \var{True} if the mode was set succesfully, \var{False}
-otherwise.
-
-Note that the video mode may not always be set. E.g. a console on Linux
-or a telnet session cannot always set the mode. It is important to check
-the error value returned by this function if it was not succesful.
-
-The mode can be set when the video driver has not yet been initialized
-(i.e. before \seep{InitVideo} was called) In that case, the video mode will
-be stored, and after the driver was initialized, an attempt will be made to
-set the requested mode. Changing the video driver before the call to
-\var{InitVideo} will clear the stored video mode.
-
-To know which modes are valid, use the \seef{GetVideoModeCount} and
-\seef{GetVideoModeData} functions. To retrieve the current video mode, 
-use the \seep{GetVideoMode} procedure.
-\Errors
-If the specified mode cannot be set, then \var{errVioNoSuchMode} may be set
-in \var{ErrorCode}
-\SeeAlso
-\seef{GetVideoModeCount}
-\seef{GetVideoModeData}
-\seep{GetVideoMode}
-\end{function}
-
-\begin{procedure}{UnlockScreenUpdate}
-\Declaration
-Procedure UnlockScreenUpdate;
-\Description
-\var{UnlockScreenUpdate} decrements the screen update lock count with one if
-it is larger than zero. When the lock count reaches zero, the 
-\seep{UpdateScreen} will actually update the screen. No screen update will 
-be performed as long as the screen update lock count is nonzero. This 
-mechanism can be used to increase screen performance in case a lot of 
-writing is done. 
-
-It is important to make sure that each call to \seep{LockScreenUpdate} is
-matched by exactly one call to \var{UnlockScreenUpdate}
-\Errors
-None.
-\SeeAlso
-\seep{LockScreenUpdate}, \seef{GetLockScreenCount}, \seep{UpdateScreen}
-\end{procedure}
-
-For an example, see \seef{GetLockScreenCount}.
-
-\begin{procedure}{UpdateScreen}
-\Declaration
-procedure UpdateScreen(Force: Boolean); 
-\Description
-\var{UpdateScreen} synchronizes the actual screen with the contents
-of the \var{VideoBuf} internal buffer. The parameter \var{Force}
-specifies whether the whole screen has to be redrawn (\var{Force=True})
-or only parts that have changed since the last update of the screen.
-
-The \var{Video} unit keeps an internal copy of the screen as it last 
-wrote it to the screen (in the \var{OldVideoBuf} array). The current 
-contents of \var{VideoBuf} are examined to see what locations on the 
-screen need to be updated. On slow terminals (e.g. a \linux telnet 
-session) this mechanism can speed up the screen redraw considerably.
-\Errors
-None.
-\SeeAlso
-\seep{ClearScreen}
-\end{procedure}
-
-For an example, see most other functions.
-
-\section{Writing a custom video driver}
-\label{se:viddriver}
-Writing a custom video driver is not difficult, and generally means
-implementing a couple of functions, which whould be registered with
-the \seef{SetVideoDriver} function. The various functions that can be
-implemented are located in the \var{TVideoDriver} record:
-\begin{verbatim}
-TVideoDriver = Record
-  InitDriver        : Procedure;
-  DoneDriver        : Procedure;
-  UpdateScreen      : Procedure(Force : Boolean);
-  ClearScreen       : Procedure;
-  SetVideoMode      : Function (Const Mode : TVideoMode) : Boolean;
-  GetVideoModeCount : Function : Word;
-  GetVideoModeData  : Function(Index : Word; Var Data : TVideoMode) : Boolean;
-  SetCursorPos      : procedure (NewCursorX, NewCursorY: Word);
-  GetCursorType     : function : Word;
-  SetCursorType     : procedure (NewType: Word);
-  GetCapabilities   : Function : Word;
-end;
-\end{verbatim}
-Not all of these functions must be implemented. In fact, the only absolutely
-necessary function to write a functioning driver is the \var{UpdateScreen} 
-function. The general calls in the \file{Video} unit will check which
-functionality is implemented by the driver.
-
-The functionality of these calls is the same as the functionality of the
-calls in the video unit, so the expected behaviour can be found in the
-previous section. Some of the calls, however, need some additional remarks.
-\begin{description}
-\item[InitDriver] Called by \var{InitVideo}, this function should initialize 
-any data structures needed for the functionality of the driver, maybe do some 
-screen initializations. The function is guaranteed to be called only once; It 
-can only be called again after a call to \var{DoneVideo}. The variables
-\var{ScreenWidth} and \var{ScreenHeight} should be initialized correctly
-after a call to this function, as the \var{InitVideo} call will initialize
-the \var{VideoBuf} and \var{OldVideoBuf} arrays based on their values.
-\item[DoneDriver] This should clean up any structures that have been
-initialized in the \var{InitDriver} function. It should possibly also
-restore the screen as it was before the driver was initialized. The VideoBuf
-and \var{OldVideoBuf} arrays will be disposed of by the general \var{DoneVideo}
-call.
-\item[UpdateScreen] This is the only required function of the driver. It
-should update the screen based on the \var{VideoBuf} array's contents. It
-can optimize this process by comparing the values with values in the
-\var{OldVideoBuf} array. After updating the screen, the \var{UpdateScreen}
-procedure should update the \var{OldVideoBuf} by itself. If the \var{Force}
-parameter is \var{True}, the whole screen should be updated, not just the
-changed values.
-\item[ClearScreen] If there is a faster way to clear the screen than to
-write spaces in all character cells, then it can be implemented here. If the
-driver does not implement this function, then the general routines will
-write spaces in all video cells, and will call \var{UpdateScreen(True)}.
-\item[SetVideoMode] Should set the desired video mode, if available. It
-should return \var{True} if the mode was set, \var{False} if not.
-\item[GetVideoModeCount] Should return the number of supported video modes.
-If no modes are supported, this function should not be implemented; the
-general routines will return 1. (for the current mode)
-\item[GetVideoModeData] Should return the data for the \var{Index}-th mode;
-\var{Index} is zero based. The function should return true if the data was
-returned correctly, false if \var{Index} contains an invalid index.
-If this is not implemented, then the general routine will return the current 
-video mode when \var{Index} equals 0.
-\item[GetCapabilities] If this function is not implemented, zero (i.e.
-no capabilities) will be returned by the general function.
-\end{description}
-
-The following unit shows how to override a video driver, with a driver
-that writes debug information to a file.
-
-\FPCexample{viddbg}
-
-The unit can be used in any of the demonstration programs, by simply
-including it in the \var{uses} clause. Setting \var{DetailedVideoLogging} to
-\var{True} will create a more detailed log (but will also slow down
-functioning)