paweld/fpc
1
0
Fork 0
mirror of https://gitlab.com/freepascal.org/fpc/source.git synced 2026-01-03 15:33:16 +01:00
Code Issues Packages Projects Releases Wiki Activity

Switched to new fpc style file

Browse Source
This commit is contained in:
michael 1998-12-11 23:18:50 +00:00
parent cbc6210e24
commit c065388019
13 changed files with 3969 additions and 2144 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

385
docs/crt.tex
View File

@ -22,21 +22,18 @@
\label{ch:crtunit}
This chapter describes the \var{CRT} unit for Free Pascal, both under \dos
and \linux. 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{mmay@dnaco.net}}, and enhanced by Micha\"el Van Canneyt
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 an earlier of the
compiler) the crt unit automatically cleared the screen at program startup.
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}
\section{Types, Variables, Constants}
Color definitions :
\begin{verbatim}
@ -105,230 +102,371 @@ screen. It is defined on \dos only.
\begin{verbatim}
var lastmode : Word;
\end{verbatim}
\section{Procedures and Functions}
\begin{procedure}{AssignCrt}
\Declaration
Procedure AssignCrt (Var F: Text);
\Description
\procedure{AssignCrt}{(Var F: Text)}
{
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.
}
{None.}{\seep{Window}}
\Errors
None.
\SeeAlso
\seep{Window}
\end{procedure}
\latex{\inputlisting{crtex/ex1.pp}}
\html{\input{crtex/ex1.tex}}
\begin{procedure}{BigCursor}
\Declaration
Procedure BigCursor ;
\Procedure{BigCursor}{Makes the cursor a big rectangle.
Not implemented on \linux.}
{None.}{\seep{CursorOn}, \seep{CursorOff}}
\Procedure {ClrEol}
{ ClrEol clears the current line, starting from the cursor position, to the
end of the window. The cursor doesn't move}
{None.}{\seep{DelLine}, \seep{InsLine}, \seep{ClrScr}}
\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}
\latex{\inputlisting{crtex/ex9.pp}}
\html{\input{crtex/ex9.tex}}
\begin{procedure}{ClrScr}
\Declaration
Procedure ClrScr ;
\procedure {ClrScr}{}
{ ClrScr clears the current window (using the current colors),
\Description
ClrScr clears the current window (using the current colors),
and sets the cursor in the top left
corner of the current window.}
{None.}{ \seep{Window} }
corner of the current window.
\Errors
None.
\SeeAlso
\seep{Window}
\end{procedure}
\latex{\inputlisting{crtex/ex8.pp}}
\html{\input{crtex/ex8.tex}}
\begin{procedure}{CursorOff}
\Declaration
Procedure CursorOff ;
\Procedure{CursorOff}{Switches the cursor off (i.e. the cursor is no
\Description
Switches the cursor off (i.e. the cursor is no
longer visible).
Not implemented on \linux.
\Errors
None.
\SeeAlso
\seep{CursorOn}, \seep{BigCursor}
\end{procedure}
\begin{procedure}{CursorOn}
\Declaration
Procedure CursorOn ;
Not implemented on \linux.}
{None.}{\seep{CursorOn}, \seep{BigCursor}}
\Procedure{CursorOn}{Switches the cursor on.
Not implemented on \linux.}
{None.}{\seep{BigCursor}, \seep{CursorOff}}
\procedure{Delay}{(DTime: Word)}
{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.}
{None}{\seep{Sound}, \seep{NoSound}}
\Description
Switches the cursor on.
Not implemented on \linux.
\Errors
None.
\SeeAlso
\seep{BigCursor}, \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}
\latex{\inputlisting{crtex/ex15.pp}}
\html{\input{crtex/ex15.tex}}
\begin{procedure}{DelLine}
\Declaration
Procedure DelLine ;
\Procedure {DelLine}
{ DelLine removes the current line. Lines following the current line are
\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.}
{None.}{\seep{ClrEol}, \seep{InsLine}, \seep{ClrScr}}
current window. The cursor doesn't move.
\Errors
None.
\SeeAlso
\seep{ClrEol}, \seep{InsLine}, \seep{ClrScr}
\end{procedure}
\latex{\inputlisting{crtex/ex11.pp}}
\html{\input{crtex/ex11.tex}}
\begin{procedure}{GotoXY}
\Declaration
Procedure GotoXY (X: Byte; Y: Byte);
\procedure {GotoXY}{(X: Byte; Y: Byte)}
{ Positions the cursor at \var{(X,Y)}, \var{X} in horizontal, \var{Y} in
\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.
}
{None.}{ \seef{WhereX}, \seef{WhereY}, \seep{Window} }
\Errors
None.
\SeeAlso
\seef{WhereX}, \seef{WhereY}, \seep{Window}
\end{procedure}
\latex{\inputlisting{crtex/ex6.pp}}
\html{\input{crtex/ex6.tex}}
\begin{procedure}{HighVideo}
\Declaration
Procedure HighVideo ;
\procedure {HighVideo}{}
{ HighVideo switches the output to highlighted text. (It sets the high
\Description
HighVideo switches the output to highlighted text. (It sets the high
intensity bit of the video attribute)
}
{None.}{ \seep{TextColor}, \seep{TextBackground}, \seep{LowVideo},
\seep{NormVideo}}
\Errors
None.
\SeeAlso
\seep{TextColor}, \seep{TextBackground}, \seep{LowVideo},
\seep{NormVideo}
\end{procedure}
\latex{\inputlisting{crtex/ex14.pp}}
\html{\input{crtex/ex14.tex}}
\begin{procedure}{InsLine}
\Declaration
Procedure InsLine ;
\procedure {InsLine}{}
{ InsLine inserts an empty line at the current cursor position.
\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.}
{None.}{\seep{ClrEol}, \seep{DelLine}, \seep{ClrScr}}
The cursor doesn't move.
\Errors
None.
\SeeAlso
\seep{ClrEol}, \seep{DelLine}, \seep{ClrScr}
\end{procedure}
\latex{\inputlisting{crtex/ex10.pp}}
\html{\input{crtex/ex10.tex}}
\begin{function}{KeyPressed}
\Declaration
Function KeyPressed : Boolean;
\Function {KeyPressed}{Boolean}
{ The Keypressed function scans the keyboard buffer and sees if a key has
\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.
}
{None.}{\seef{ReadKey}}
\Errors
None.
\SeeAlso
\seef{ReadKey}
\end{function}
\latex{\inputlisting{crtex/ex2.pp}}
\html{\input{crtex/ex2.tex}}
\begin{procedure}{LowVideo}
\Declaration
Procedure LowVideo ;
\Procedure {LowVideo}
{ LowVideo switches the output to non-highlighted text. (It clears the high
\Description
LowVideo switches the output to non-highlighted text. (It clears the high
intensity bit of the video attribute)
}
{None.}{ \seep{TextColor}, \seep{TextBackground}, \seep{HighVideo},
\seep{NormVideo}}
\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 ;
\Procedure {NormVideo}
{ NormVideo switches the output to the defaults, read at startup. (The
\Description
NormVideo switches the output to the defaults, read at startup. (The
defaults are read from the cursor position at startup)
}
{None.}{ \seep{TextColor}, \seep{TextBackground}, \seep{LowVideo},
\seep{HighVideo}}
\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
\Procedure{NoSound}{
Stops the speaker sound.
This is not supported in \linux}{None.}{\seep{Sound}}
This is not supported in \linux
\Errors
None.
\SeeAlso
\seep{Sound}
\end{procedure}
\latex{\inputlisting{crtex/ex16.pp}}
\html{\input{crtex/ex16.tex}}
\begin{function}{ReadKey}
\Declaration
Function ReadKey : Char;
\Description
\Function {ReadKey}{Char}
{
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.
}
{None.}{\seef{KeyPressed}}
\Errors
None.
\SeeAlso
\seef{KeyPressed}
\end{function}
\latex{\inputlisting{crtex/ex3.pp}}
\html{\input{crtex/ex3.tex}}
\begin{procedure}{Sound}
\Declaration
Procedure Sound (hz : word);
\Description
Sounds the speaker at a frequency of \var{hz}.
This is not supported in \linux
\Errors
None.
\SeeAlso
\seep{NoSound}
\end{procedure}
\begin{procedure}{TextBackground}
\Declaration
Procedure TextBackground (CL: Byte);
\procedure{Sound}{(hz : word)}
{ Sounds the speaker at a frequency of \var{hz}.
\Description
This is not supported in \linux}{None.}{\seep{NoSound}}
\procedure {TextBackground}{(CL: Byte)}
{
TextBackground sets the background color to \var{CL}. \var{CL} can be one of the
predefined color constants.
}
{None.}{ \seep{TextColor}, \seep{HighVideo}, \seep{LowVideo},
\seep{NormVideo}}
\Errors
None.
\SeeAlso
\seep{TextColor}, \seep{HighVideo}, \seep{LowVideo},
\seep{NormVideo}
\end{procedure}
\latex{\inputlisting{crtex/ex13.pp}}
\html{\input{crtex/ex13.tex}}
\begin{procedure}{TextColor}
\Declaration
Procedure TextColor (CL: Byte);
\Description
\procedure {TextColor}{(CL: Byte)}
{
TextColor sets the foreground color to \var{CL}. \var{CL} can be one of the
predefined color constants.
}
{None.}{ \seep{TextBackground}, \seep{HighVideo}, \seep{LowVideo},
\seep{NormVideo}}
\Errors
None.
\SeeAlso
\seep{TextBackground}, \seep{HighVideo}, \seep{LowVideo},
\seep{NormVideo}
\end{procedure}
\latex{\inputlisting{crtex/ex12.pp}}
\html{\input{crtex/ex12.tex}}
\begin{function}{WhereX}
\Declaration
Function WhereX : Byte;
\Description
\Function {WhereX}{Byte}
{
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.
}
{None.}{ \seep{GotoXY}, \seef{WhereY}, \seep{Window} }
\Errors
None.
\SeeAlso
\seep{GotoXY}, \seef{WhereY}, \seep{Window}
\end{function}
\latex{\inputlisting{crtex/ex7.pp}}
\html{\input{crtex/ex7.tex}}
\begin{function}{WhereY}
\Declaration
Function WhereY : Byte;
\Description
\Function {WhereY}{Byte}
{
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.
}
{None.}{ \seep{GotoXY}, \seef{WhereX}, \seep{Window} }
\Errors
None.
\SeeAlso
\seep{GotoXY}, \seef{WhereX}, \seep{Window}
\end{function}
\latex{\inputlisting{crtex/ex7.pp}}
\html{\input{crtex/ex7.tex}}
\begin{procedure}{Window}
\Declaration
Procedure Window (X1, Y1, X2, Y2: Byte);
\procedure {Window}{(X1, Y1, X2, Y2: Byte)}
{ Window creates a window on the screen, to which output will be sent.
\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.
}
{None.}{\seep{GotoXY}, \seef{WhereX}, \seef{WhereY}, \seep{ClrScr}}
\Errors
None.
\SeeAlso
\seep{GotoXY}, \seef{WhereX}, \seef{WhereY}, \seep{ClrScr}
\end{procedure}
\latex{\inputlisting{crtex/ex5.pp}}
\html{\input{crtex/ex5.tex}}
\begin{procedure}{ScrollWindow}
\Declaration
Procedure ScrollWindow (X1,Y1,X2,Y2 : Byte; Count : Longint);
%\procedure {ScrollWindow}{(X1,Y1,X2,Y2 : Byte; Count : Longint)}
%{ ScrollWindow scrolls the contents of the window defined by the upper-left
\Description
ScrollWindow scrolls the contents of the window defined by the upper-left
%\var{(X1,Y1)} and lower-right \var{(X2,Y2)} corners \var{count} lines up if
%\var{count} is positive, it scrolls down if \var{count} is negative.
%The new lines are made blank using the current textcolors.
%}
%{None.}{\seep{Window}, \seep{ClrScr}}
%
\Errors
None.
\SeeAlso
\seep{Window}, \seep{ClrScr}
\end{procedure}
\begin{function}{SaveScreenRegion}
\Declaration
Function SaveScreenRegion (X1,Y1,X2,Y2, var P : pointer) : Boolean;
%\function {SaveScreenRegion}{(X1,Y1,X2,Y2, var P : pointer)}{Boolean}
%{SaveScreenRegion writes the the contents of the window defined by the upper-left
\Description
SaveScreenRegion writes the the contents of the window defined by the upper-left
%\var{(X1,Y1)} and lower-right \var{(X2,Y2)} corners to the location pointed
%to by \var{P}. If \var{P} is \var{nil} then enough memory is allocated to
%contain the contents of the window.
@ -339,17 +477,28 @@ are relative to the window's top left corner.
%\var{(Y2-Y1+1)*(X2-X1+1)*2} bytes.
%
%The function returns \var{False} if it couldn't allocate the required
%memory, \var{True} if the memory was allocated.}{None.}
%{\seep{RestoreScreenRegion}, \seep{Window} }
%memory, \var{True} if the memory was allocated.
\Errors
None.
\SeeAlso
\seep{RestoreScreenRegion}, \seep{Window}
\end{function}
\begin{procedure}{RestoreScreenRegion}
\Declaration
Procedure RestoreScreenRegion (X1,Y1,X2,Y2, var P : pointer);
%\procedure {RestoreScreenRegion}{(X1,Y1,X2,Y2, var P : pointer)}
%{SaveScreenRegion writes the the contents of the memory location pointed to
\Description
SaveScreenRegion writes the the contents of the memory location pointed to
%by \var{P}, to the window defined by the upper-left \var{(X1,Y1)} and
%lower-right \var{(X2,Y2)} corners.
%
%The contents of \var{P} should be arranged as if they are when written by
%a call to the SaveScreenRegion () function.
%
%The memory pointed to by \var{P} is NOT freed.}{None}
%{\seef{SaveScreenRegion}, \seep{Window} }
%The memory pointed to by \var{P} is NOT freed.
\Errors
None
\SeeAlso
\seef{SaveScreenRegion}, \seep{Window}
\end{procedure}

540
docs/dos.tex
View File

@ -21,21 +21,18 @@
\chapter{The DOS unit.}
This chapter describes the \var{DOS} unit for Free pascal, both under \dos
and \linux. 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{mmay@dnaco.net}}, and enhanced by Micha\"el Van
Canneyt.
Under \linux, some of the functionality is lost, as it is either impossible
or meaningless to implement it. Other than that,
the functionality for both operating systems is the same.
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 DOS unit.
\end{itemize}
\section{Types, Variables, Constants}
\subsection {Constants}
The DOS unit implements the following constants:
@ -47,7 +44,6 @@ The DOS unit implements the following constants:
fzero = $0040;
fsign = $0080;
foverflow = $0800;
{Bitmasks for file attribute}
readonly = $01;
hidden = $02;
@ -100,7 +96,6 @@ different from \dos's, and the calls have to be mimicked.
\begin{verbatim}
const
filerecnamelength = 255;
type
FileRec = Packed Record
Handle,
@ -117,7 +112,6 @@ Text files are handled by the following types :
const
TextRecNameLength = 256;
TextRecBufSize = 256;
type
TextBuf = array[0..TextRecBufSize-1] of char;
TextRec = Packed Record
@ -162,7 +156,6 @@ The \var{registers} type is used in the \var{MSDos} call.
\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;
@ -187,18 +180,18 @@ Other values are possible, but are not documented.
%\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.
\section{Functions and Procedures}
\begin{procedure}{AddDisk}
\Declaration
Procedure AddDisk (Const S : String);
\procedure{AddDisk}{(Const S : String)}
{\var{AddDisk} adds a filename \var{S} to the internal list of disks. It is
\Description
\var{AddDisk} adds a filename \var{S} to the internal list of disks. It is
implemented for \linux only.
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}
@ -210,21 +203,27 @@ initialization code presets the first three disks to:
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:'})
}{None}{\seef{DiskFree}, \seef{DiskSize} }
\function{DiskFree}{(Drive: byte)}{longint}{
\Errors
None
\SeeAlso
\seef{DiskFree}, \seef{DiskSize}
\end{procedure}
\begin{function}{DiskFree}
\Declaration
Function DiskFree (Drive: byte) : longint;
\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.
Typically, the free space is the size of a disk block, multiplied by the
number of free blocks on the disk.
\textbf{For \linux 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}
@ -235,20 +234,25 @@ been preset to :
\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.
}{-1 when a failure occurs, or an invalid \var{drivenr} is given.}
{\seef{DiskSize}, \seep{AddDisk}}
\Errors
-1 when a failure occurs, or an invalid \var{drivenr} is given.
\SeeAlso
\seef{DiskSize}, \seep{AddDisk}
\end{function}
\latex{\inputlisting{dosex/ex6.pp}}
\html{\input{dosex/ex6.tex}}
\begin{function}{DiskSize}
\Declaration
Function DiskSize (Drive: byte) : longint;
\Description
\function{DiskSize}{(Drive: byte)}{longint}{
\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 \linux 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.
@ -262,166 +266,268 @@ been preset to :
\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.
}{-1 when a failure occurs, or an invalid drive number is given.}
{\seef{DiskFree}, \seep{AddDisk}}
\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
\Function{DosExitCode}{Word}{
\var{DosExitCode} contains (in the low byte) the exit-code of a program
executed with the \var{Exec} call.}{None.}{\seep{Exec}}
executed with the \var{Exec} call.
\Errors
None.
\SeeAlso
\seep{Exec}
\end{function}
\latex{\inputlisting{dosex/ex5.pp}}
\html{\input{dosex/ex5.tex}}
\begin{function}{DosVersion}
\Declaration
Function DosVersion : Word;
\Function{DosVersion}{Word}
{\var{DosVersion} returns the \dos version number. On \linux systems, it
\Description
\var{DosVersion} returns the \dos version number. On \linux systems, it
returns the Linux version (The first 2 numbers, e.g Linux version 2.1.76 will
give you DosVersion 2.1)}{None.}{}
give you DosVersion 2.1)
\Errors
None.
\SeeAlso
\end{function}
\latex{\inputlisting{dosex/ex1.pp}}
\html{\input{dosex/ex1.tex}}
\begin{function}{EnvCount}
\Declaration
Function EnvCount : longint;
\Description
\var{EnvCount} returns the number of environment variables.
\Errors
None.
\SeeAlso
\seef{EnvStr}, \seef{GetEnv}
\end{function}
\begin{function}{EnvStr}
\Declaration
Function EnvStr (Index: integer) : string;
\Description
\Function{EnvCount}{longint}{
\var{EnvCount} returns the number of environment variables.}
{None.}{\seef{EnvStr}, \seef{GetEnv}}
\function{EnvStr}{(Index: integer)}{string}{
\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.}
{The length is limited to 255 characters. This may cause problems under
\linux. The \linux unit solves this problem.}{\seef{EnvCount}, \seef{GetEnv}}
The index of the first pair is zero.
\Errors
The length is limited to 255 characters. This may cause problems under
\linux. The \linux unit solves this problem.
\SeeAlso
\seef{EnvCount}, \seef{GetEnv}
\end{function}
\latex{\inputlisting{dosex/ex13.pp}}
\html{\input{dosex/ex13.tex}}
\begin{procedure}{Exec}
\Declaration
Procedure Exec (const Path: pathstr; const ComLine: comstr);
\Description
\procedure{Exec}{(const Path: pathstr; const ComLine: comstr)}{
\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 are reported in \var{DosError}.}{\seef{DosExitCode}}
\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
\functionl{FExpand}{Dos:FExpand}{(const path: pathstr)}{pathstr}{
\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 (under \dos).
The resulting name is converted to uppercase on \dos systems. Under \linux,
the name is left as it is. (filenames are case sensitive under Unix)
}{\seep{FSplit}}
\latex{\inputlisting{dosex/ex5.pp}}
\Errors
\seep{FSplit}
\SeeAlso
\inputlisting{dosex/ex5.pp}
\end{functionl}
\html{\input{dosex/ex5.tex}}
\begin{procedure}{FindClose}
\Declaration
Procedure FindClose (Var F: SearchRec);
\Description
\procedure{FindClose}{(Var F: SearchRec)}{
\textbf{\linux only}
Under \linux, the \var{findfirst/findnext} calls have to be mimicked.
An internal table of file descriptors is kept.
When using different \var{searchrecs} at the same time,
the system may run out of file descriptors for directories.
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.
It is recommended to use the \linux call \var{Glob} when looking for files.
}{None.}{\seef{Glob}.}
\procedure{FindFirst}{(const Path: pathstr; Attr: word; var F: SearchRec)}{
\Errors
None.
\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}, checks the
atrributes specified in \var{Attr}. 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.}{Errors are reported in DosError.}{\seep{FindNext},
\seep{FindClose}}
was(were) found.
\Errors
Errors are reported in DosError.
\SeeAlso
\seep{FindNext},
\seep{FindClose}
\end{procedure}
\latex{\inputlisting{dosex/ex7.pp}}
\html{\input{dosex/ex7.tex}}
\begin{procedure}{FindNext}
\Declaration
Procedure FindNext (var f: searchRec);
\Description
\procedure{FindNext}{(var f: searchRec)}{
\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.}{\var{DosError} is used to report errors.}
{\seep{FindFirst}, \seep{FindClose}}
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;
\functionl{FSearch}{Dos:FSearch}{(Path: pathstr; DirList: string)}{pathstr}
{\var{FSearch} searches the file \var{Path} in all directories listed in
\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 (or
colons under \linux).
When no file is found, an empty string is returned.
}{None.}{\seefl{FExpand}{Dos:FExpand}}
\Errors
None.
\SeeAlso
\seefl{FExpand}{Dos:FExpand}
\end{functionl}
\latex{\inputlisting{dosex/ex10.pp}}
\html{\input{dosex/ex10.tex}}
\procedure{FSplit}{(path: pathstr; \\ var dir: dirstr; var name: namestr;
var ext: extstr)}{
\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}.)
Under \linux, the extension is taken to be all letters after the last dot
(.).
}{None.}{\seefl{FSearch}{Dos:FSearch}}
\Errors
None.
\SeeAlso
\seefl{FSearch}{Dos:FSearch}
\end{procedure}
\latex{\inputlisting{dosex/ex12.pp}}
\html{\input{dosex/ex12.tex}}
\begin{procedure}{GetCBreak}
\Declaration
Procedure GetCBreak (var breakvalue: boolean);
\Description
\procedure{GetCBreak}{(var breakvalue: boolean)}{
\var{GetCBreak} gets the status of CTRL-Break checking under \dos.
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.}{Under Linux, this exists but is
not implemented, i.e. the call does nothing.}{\seep{SetCBreak}}
then a check is done at every system call.
\Errors
Under Linux, this exists but is
not implemented, i.e. the call does nothing.
\SeeAlso
\seep{SetCBreak}
\end{procedure}
\begin{procedurel}{GetDate}{Dos:GetDate}
\Declaration
Procedure GetDate (var year, month, mday, wday: word);
\Description
\procedurel{GetDate}{Dos:GetDate}{(var year, month, mday, wday: word)}{
\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.}
{None.}{\seepl{GetTime}{Dos:GetTime},\seep{SetDate}}
\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}
\latex{\inputlisting{dosex/ex2.pp}}
\html{\input{dosex/ex2.tex}}
\begin{functionl}{GetEnv}{Dos:GetEnv}
\Declaration
Function GetEnv (EnvVar: String) : String;
\Description
\functionl{GetEnv}{Dos:GetEnv}{(EnvVar: String)}{String}{
\var{Getenv} returns the value of the environment variable \var{EnvVar}.
Under \linux, case is important when looking for \var{EnvVar}.
When there is no environment variable \var{EnvVar} defined, an empty
string is returned.}{None.}{\seef{EnvCount}, \seef{EnvStr}}
string is returned.
\Errors
None.
\SeeAlso
\seef{EnvCount}, \seef{EnvStr}
\end{functionl}
\latex{\inputlisting{dosex/ex14.pp}}
\html{\input{dosex/ex14.tex}}
\begin{procedure}{GetFAttr}
\Declaration
Procedure GetFAttr (var F; var Attr: word);
\Description
\procedure{GetFAttr}{(var F; var Attr: word)}{
\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
@ -441,86 +547,173 @@ Under \linux, supported attributes are:
\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 are reported in \var{DosError}}{\seep{SetFAttr}}
\Errors
Errors are reported in \var{DosError}
\SeeAlso
\seep{SetFAttr}
\end{procedure}
\latex{\inputlisting{dosex/ex8.pp}}
\html{\input{dosex/ex8.tex}}
\begin{procedure}{GetFTime}
\Declaration
Procedure GetFTime (var F; var Time: longint);
\Description
\procedure{GetFTime}{(var F; var Time: longint)}{
\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 are reported in \var{DosError}}
{\seep{SetFTime}, \seep{PackTime},\seep{UnPackTime}}
opened.
\Errors
Errors are reported in \var{DosError}
\SeeAlso
\seep{SetFTime}, \seep{PackTime},\seep{UnPackTime}
\end{procedure}
\latex{\inputlisting{dosex/ex9.pp}}
\html{\input{dosex/ex9.tex}}
\begin{procedure}{GetIntVec}
\Declaration
Procedure GetIntVec (IntNo: byte; var Vector: pointer);
\Description
\procedure{GetIntVec}{(IntNo: byte; var Vector: pointer)}{
\var{GetIntVec} returns the address of interrupt vector
\var{IntNo}.}{None. Under \linux, this call exists bout isn't implemented,
i.e. it does nothing.}{\seep{SetIntVec}}
\var{IntNo}.
\Errors
None. Under \linux, this call exists bout isn't implemented,
i.e. it does nothing.
\SeeAlso
\seep{SetIntVec}
\end{procedure}
\begin{procedurel}{GetTime}{Dos:GetTime}
\Declaration
Procedure GetTime (var hour, minute, second, sec100: word);
\Description
\procedurel{GetTime}{Dos:GetTime}{(var hour, minute, second, sec100: word)}{
\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.}{None.}{\seepl{GetDate}{Dos:GetDate},
\seep{SetTime}}
second.
\Errors
None.
\SeeAlso
\seepl{GetDate}{Dos:GetDate},
\seep{SetTime}
\end{procedurel}
\latex{\inputlisting{dosex/ex3.pp}}
\html{\input{dosex/ex3.tex}}
\begin{procedure}{GetVerify}
\Declaration
Procedure GetVerify (var verify: boolean);
\Description
\procedure{GetVerify}{(var verify: boolean)}{
\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.}{Under \linux, Verify is always
\var{True}.}{\seep{SetVerify}}
written to disk are not verified.
\Errors
Under \linux, Verify is always
\var{True}.
\SeeAlso
\seep{SetVerify}
\end{procedure}
\begin{procedure}{Intr}
\Declaration
Procedure Intr (IntNo: byte; var Regs: registers);
\Description
\procedure{Intr}{(IntNo: byte; var Regs: registers)}{
\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}.}
{Under \linux this call does nothing, because interrupts are managed by the
kernel. The only allowed interrupt is 80h, the kernel entry interrupt.}
{\seep{MSDos}, see the \linux unit.}
returned, the processor registers are saved in \var{Regs}.
\Errors
Under \linux this call does nothing, because interrupts are managed by the
kernel. The only allowed interrupt is 80h, the kernel entry interrupt.
\SeeAlso
\seep{MSDos}, see the \linux unit.
\end{procedure}
\begin{procedure}{Keep}
\Declaration
Procedure Keep (ExitCode: word);
\Description
\procedure{Keep}{(ExitCode: word)}{
\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.}
{Under \linux, this call does nothing.}{\seem{Halt}{}}
\var{ExitCode} is the same parameter as the \var{Halt} function takes.
\Errors
Under \linux, this call does nothing.
\SeeAlso
\seem{Halt}{}
\end{procedure}
\begin{procedure}{MSDos}
\Declaration
Procedure MSDos (var regs: registers);
\Description
\procedure{MSDos}{(var regs: registers)}{
\var{MSDos} executes an MS-\dos call (int 21h). This is the same as doing a
\var{Intr} call with an interrupt number of 21h.}{None.}{\seep{Intr}}
\var{Intr} call with an interrupt number of 21h.
\Errors
None.
\SeeAlso
\seep{Intr}
\end{procedure}
\begin{procedure}{PackTime}
\Declaration
Procedure PackTime (var T: datetime; var P: longint);
\Description
\procedure{PackTime}{(var T: datetime; var P: longint)}{
\var{UnPackTime} converts the date and time specified in \var{T}
to a packed-time format which can be fed to \var{SetFTime}.}
{None.}
{\seep{SetFTime}, \seep{FindFirst}, \seep{FindNext}, \seep{UnPackTime}}
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}
\latex{\inputlisting{dosex/ex4.pp}}
\html{\input{dosex/ex4.tex}}
\begin{procedure}{SetCBreak}
\Declaration
Procedure SetCBreak (breakvalue: boolean);
\Description
\procedure{SetCBreak}{(breakvalue: boolean)}{
\var{SetCBreak} sets the status of CTRL-Break checking under \dos.
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.}{Under Linux, this call exists
but is not implemented, i.e. it does nothing.}{\seep{GetCBreak}}
then a check is done at every system call.
\Errors
Under Linux, this call exists
but is not implemented, i.e. it does nothing.
\SeeAlso
\seep{GetCBreak}
\end{procedure}
\begin{procedure}{SetDate}
\Declaration
Procedure SetDate (year,month,day: word);
\Description
\procedure{SetDate}{(year,month,day: word)}{
\var{SetDate} sets the system's internal date. \var{Year} is a number
between 1980 and 2099.}
{On a \linux machine, this is not implemented (allthough a procedure
between 1980 and 2099.
\Errors
On a \linux machine, this is not implemented (allthough a procedure
exists, it just doesn't do anything. The setting of the date is a
root-only privilege, and is hence not implemented.}{\seep{GetDate},
\seep{SetTime}}
root-only privilege, and is hence not implemented.
\SeeAlso
\seep{GetDate},
\seep{SetTime}
\end{procedure}
\begin{procedure}{SetFAttr}
\Declaration
Procedure SetFAttr (var F; Attr: word);
\Description
\procedure{SetFAttr}{(var F; Attr: word)}{
\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
@ -534,54 +727,101 @@ following constants:
\item \var{Archive = 20h}
\item \var{AnyFile = 3fh}
\end{itemize}
}{Errors are reported in \var{DosError}.
Under \linux the call exists, but is not implemented, i.e. it does nothing.}
{\seep{GetFAttr}}
\Errors
Errors are reported in \var{DosError}.
Under \linux the call exists, but is not implemented, i.e. it does nothing.
\SeeAlso
\seep{GetFAttr}
\end{procedure}
\begin{procedure}{SetFTime}
\Declaration
Procedure SetFTime (var F; Time: longint);
\Description
\procedure{SetFTime}{(var F; Time: longint)}{
\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.}{Errors are reported in \var{DosError}}
{\seep{GetFTime}, \seep{PackTime},\seep{UnPackTime}}
opened.
\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
\procedure{SetIntVec}{(IntNo: byte; Vector: pointer)}{
\var{SetIntVec} sets interrupt vector \var{IntNo} to \var{Vector}.
\var{Vector} should point to an interrupt procedure.}{Under \linux, this
call exists but is not implemented, the kernel manages all interrupts.}
{\seep{GetIntVec}}
\var{Vector} should point to an interrupt procedure.
\Errors
Under \linux, this
call exists but is not implemented, the kernel manages all interrupts.
\SeeAlso
\seep{GetIntVec}
\end{procedure}
\begin{procedure}{SetTime}
\Declaration
Procedure SetTime (hour,minute,second,sec100: word);
\Description
\procedure{SetTime}{(hour,minute,second,sec100: word)}{
\var{SetTime} sets the system's internal clock. The \var{Hour} parameter is
on a 24-hour time scale.}{this call exists, but is not implemented on \linux,
as setting the time is a root-only privilege.}
{\seep{GetTime}, \seep{SetDate}}
on a 24-hour time scale.
\Errors
this call exists, but is not implemented on \linux,
as setting the time is a root-only privilege.
\SeeAlso
\seep{GetTime}, \seep{SetDate}
\end{procedure}
\begin{procedure}{SetVerify}
\Declaration
Procedure SetVerify (verify: boolean);
\Description
\procedure{SetVerify}{(verify: boolean)}{
\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.}{Under \linux, Verify is always
\var{True}.}{\seep{SetVerify}}
written to disk are not verified.
\Errors
Under \linux, Verify is always
\var{True}.
\SeeAlso
\seep{SetVerify}
\end{procedure}
\begin{procedure}{SwapVectors}
\Declaration
Procedure SwapVectors ;
\Description
\Procedure{SwapVectors}{
\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.
}{Under \linux this call does nothing, as the interrupt vectors are
managed by the kernel.}{\seep{Exec}, \seep{SetIntVec}}
\Errors
Under \linux this call does nothing, as the interrupt vectors are
managed by the kernel.
\SeeAlso
\seep{Exec}, \seep{SetIntVec}
\end{procedure}
\begin{procedure}{UnPackTime}
\Declaration
Procedure UnPackTime (p: longint; var T: datetime);
\Description
\procedure{UnPackTime}{(p: longint; var T: datetime)}{
\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.}
{None.}
{\seep{GetFTime}, \seep{FindFirst}, \seep{FindNext}, \seep{PackTime}}
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}.

52
docs/fpc-html.tex
View File

@ -20,32 +20,21 @@
%
% Dummy
\newenvironment{FPCList}{\begin{description}}{\end{description}}
\newcommand{\functionl}[7]{
\subsection{#1}
\label{fu:#2}
\index{#1}
\subsubsection*{Declaration:}
\texttt {Function #1 #3 : #4;}
\subsubsection*{Description:}
#5
\subsubsection*{Errors:}
#6
\subsubsection*{See also:}
#7
}
\newcommand{\procedurel}[6]{
\subsection{#1}
\label{pro:#2}
\index{#1}
\subsubsection*{Declaration:}
\texttt {Procedure #1 #3 ;}
\subsubsection*{Description:}
#4
\subsubsection*{Errors:}
#5
\subsubsection*{See also:}
#6
}
%
%
\newcommand{\Declaration}{\item[Declaration]\ttfamily}
\newcommand{\Description}{\item[Description]\rmfamily}
\newcommand{\Errors}{\item[Errors]\rmfamily}
\newcommand{\SeeAlso}{\item[See also]\rmfamily}
%
% The environments
%
\newenvironment{functionl}[2]{\subsection{#1}%
\index{#1}\label{fu:#2}\begin{FPCList}}{\end{FPCList}}
\newenvironment{procedurel}[2]{\subsection{#1}%
\index{#1}\label{pro:#2}\begin{FPCList}}{\end{FPCList}}
\newenvironment{function}[1]{\begin{functionl}{#1}{#1}}{\end{functionl}}
\newenvironment{procedure}[1]{\begin{procedurel}{#1}{#1}}{\end{procedurel}}
\newcommand{\seefl}[2]{
\htmlref{#1}{fu:#2}
}
@ -65,17 +54,8 @@
\newcommand{\var}[1]{\texttt {#1}}
\newcommand{\file}[1]{\textsf {#1}}
%
% procedures without args
% Abbreviations
%
\newcommand{\Procedurel}[5]{\procedurel{#1}{#2}{}{#3}{#4}{#5}}
\newcommand{\Functionl}[6]{\functionl{#1}{#2}{}{#3}{#4}{#5}{#6}}
%
% Procedures without labels.
%
\newcommand{\procedure}[5]{\procedurel{#1}{#1}{#2}{#3}{#4}{#5}}
\newcommand{\function}[6]{\functionl{#1}{#1}{#2}{#3}{#4}{#5}{#6}}
\newcommand{\Procedure}[4]{\procedure{#1}{}{#2}{#3}{#4}}
\newcommand{\Function}[5]{\function{#1}{}{#2}{#3}{#4}{#5}}
\newcommand{\linux}{\textsc{LinuX} }
\newcommand{\dos} {\textsc{dos} }
\newcommand{\msdos}{\textsc{ms-dos} }

56
docs/fpc.sty
View File

@ -80,54 +80,20 @@
}
{\end{list}}
%
% define a version of \procedure and \function
% which allows you to give a label.
%
\newcommand{\functionl}[7]{
\subsection{#1}
\raisebox{1ex}{\rule{\linewidth}{0.5mm}}
\label{fu:#2}
\index{#1}
\begin{FPCList}
\item[Declaration]
\texttt {Function #1 #3 : #4;}
\item[Description]
#5
\item[Errors]
#6
\item[See also]
#7
\end{FPCList}
}
\newcommand{\procedurel}[6]{
\subsection{#1}
\raisebox{1ex}{\rule{\linewidth}{0.5mm}}
\label{pro:#2}
\index{#1}
\begin{FPCList}
\item[Declaration]
\texttt {Procedure #1 #3;}
\item[Description]
#4
\item[Errors]
#5
\item[See also]
#6
\end{FPCList}
}
% define a capital version,
% for function/command which has no options passed to it.
\newcommand{\Functionl}[6]{\functionl{#1}{#2}{}{#3}{#4}{#5}{#6}}
\newcommand{\Procedurel}[5]{\procedurel{#1}{#2}{}{#3}{#4}{#5}}
\newcommand{\Declaration}{\item[Declaration]\ttfamily}
\newcommand{\Description}{\item[Description]\rmfamily}
\newcommand{\Errors}{\item[Errors]\rmfamily}
\newcommand{\SeeAlso}{\item[See also]\rmfamily}
%
% These versions take the function name as the label.
% The environments
%
\newcommand{\function}[6]{\functionl{#1}{#1}{#2}{#3}{#4}{#5}{#6}}
\newcommand{\procedure}[5]{\procedurel{#1}{#1}{#2}{#3}{#4}{#5}}
% define a capital version,
% for function/command which has no options passed to it.
\newcommand{\Function}[5]{\function{#1}{}{#2}{#3}{#4}{#5}}
\newcommand{\Procedure}[4]{\procedure{#1}{}{#2}{#3}{#4}}
\newenvironment{functionl}[2]{\subsection{#1}%
\index{#1}\label{fu:#2}\begin{FPCList}}{\end{FPCList}}
\newenvironment{procedurel}[2]{\subsection{#1}%
\index{#1}\label{pro:#2}\begin{FPCList}}{\end{FPCList}}
\newenvironment{function}[1]{\begin{functionl}{#1}{#1}}{\end{functionl}}
\newenvironment{procedure}[1]{\begin{procedurel}{#1}{#1}}{\end{procedurel}}
% Now the referencing commands.
%
% First, the ones with alternate label (second argument}

46
docs/getopts.tex
View File

@ -21,14 +21,12 @@
\chapter{The GETOPTS unit.}
This document describes the GETOPTS unit for Free Pascal. It was written for
\linux\ by Micha\"el Van Canneyt. It also works under DOS and Tp7.
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
@ -53,11 +51,9 @@ The \var{option} type is used to communicate the long options to \var{GetLongOpt
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.\\
@ -70,69 +66,71 @@ 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
\function {GetLongOpts}{(Shortopts : String, LongOpts : POption; var Longint
: Longint )}{Char}
{
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.
}
{ see \seef{Getopt}, \seem{getopt}{3}}
For an example, see \seef{Getopt}
\Errors
see \seef{Getopt}, \seem{getopt}{3}
\SeeAlso
Getopt
\end{function}
\begin{function}{Getopt}
\Declaration
Function Getopt (Shortopts : String) : Char;
\Description
\function {Getopt}{(Shortopts : String)}{Char}
{
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}.
}
{\seef{GetLongOpts}, \seem{getopt}{3}}
\SeeAlso
\seef{GetLongOpts}, \seem{getopt}{3}
\end{function}
\latex{\inputlisting{optex/optex.pp}}
\html{\input{optex/optex.tex}}

1107
docs/go32.tex
View File

File diff suppressed because it is too large Load Diff

1126
docs/graph.tex
View File

File diff suppressed because it is too large Load Diff

1815
docs/linux.tex
View File

File diff suppressed because it is too large Load Diff

22
docs/mmx.tex
View File

@ -54,31 +54,33 @@ initialization code.
is_mmx_cpu : boolean = false;
is_amd_3d_cpu : boolean = false;
\end{verbatim}
\section{Functions and Procedures}
\begin{procedure}{Emms}
\Declaration
Procedure Emms ;
\Procedure{Emms}
{\var{Emms} sets all floating point registers to empty. This procedure must
\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.
}
{None.}
{ \progref }
\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+}
@ -90,4 +92,4 @@ begin
{ now we can do floating point arithmetic again }
end.
\end{verbatim}
\end{FPCList}
\end{FPCList}

241
docs/mouse.tex
View File

@ -1,41 +1,32 @@
\chapter{The Mouse unit}
The mouse unit provides basic Mouse handling under Dos (Go32v1 and Go32v2)
Some general remarks about the mouse unit:
\begin{itemize}
\item The mouse driver does not know when the text screen scrolls. This results
in unerased mouse cursors on the screen when the screen scrolls while the
mouse cursor is visible. The solution is to hide the mouse cursor (using
HideMouse) when you write something to the screen and to show it again
afterwards (using ShowMouse).
\item All Functions/Procedures that return and/or accept coordinates of the mouse
cursor, always do so in pixels and zero based (so the upper left corner of
the screen is (0,0)). To get the (column, row) in standard text mode, divide
both x and y by 8 (and add 1 if you want to have it 1 based).
\item The real resolution of graphic modes and the one the mouse driver uses can
differ. For example, mode 13h (320*200 pixels) is handled by the mouse driver
as 640*200, so you will have to multiply the X coordinates you give to the
driver and divide the ones you get from it by 2 in that mode.
\item By default the mouse unit is compiled with the conditional define
MouseCheck. This causes every procedure/function of the unit to check the
MouseFound variable prior to doing anything. Of course this is not necessary,
so if you are sure you are not calling any mouse unit procedures when no
mouse is found, you can recompile the mouse unit without this conditional
define.
\item
You will notice that several procedures/functions have longint sized
parameters while only the lower 16 bits are used. This is because FPC is
a 32 bit compiler and consequently 32 bit parameters result in faster code.
\end{itemize}
\section{Constants, types and variables}
The following constants are defined (to be used in e.g. the
\seef{GetLastButtonPress} call).
\begin{verbatim}
@ -43,16 +34,18 @@ The following constants are defined (to be used in e.g. the
RButton = 2; {right button}
MButton = 4; {middle button}
\end{verbatim}
The following variable exist:
\begin{verbatim}
MouseFound: Boolean;
\end{verbatim}
it is set to \var{True} or \var{False} in the unit's initialization code.
\section{Functions and procedures}
\begin{function}{GetLastButtonPress}
\Declaration
Function GetLastButtonPress (Button: Longint; Var x,y:Longint) : Longint;
\function{GetLastButtonPress}{(Button: Longint; Var x,y:Longint)}{Longint}{
\Description
\var{GetLastButtonPress}
Stores the position where \var{Button} was last pressed in \var{x} and
\var{y} and returns
@ -60,15 +53,22 @@ the number of times this button has been pressed since the last call to this
function with \var{Button} as parameter. For \var{Button} you can use the
\var{LButton}, \var{RButton} and \var{MButton} constants for resp. the left,
right and middle button.
For two-button mice, checking the status of the middle button seems to give
and clear the stats of the right button.
}{None.}{\seef{GetLastButtonRelease}}
\Errors
None.
\SeeAlso
\seef{GetLastButtonRelease}
\end{function}
\latex{\inputlisting{mouseex/mouse5.pp}}
\html{\input{mouseex/mouse5.tex}}
\begin{function}{GetLastButtonRelease}
\Declaration
Function GetLastButtonRelease (Button: Longint; Var x,y:Longint) : Longint;
\Description
\function{GetLastButtonRelease}{(Button: Longint; Var x,y:Longint)}{Longint}{
\var{GetLastButtonRelease}
stores the position where \var{Button} was last released in \var{x} and
\var{y} and returns
@ -76,195 +76,290 @@ the number of times this button has been released since the last call to this
function with \var{Button} as parameter. For button you can use the
\var{LButton}, \var{RButton} and \var{MButton} constants for resp.
the left, right and middle button.
For two-button mice, checking the stats of the middle button seems to give
and clear the stats of the right button.
}{None.}{\seef{GetLastButtonPress}}
\Errors
None.
\SeeAlso
\seef{GetLastButtonPress}
\end{function}
For an example, see \seef{GetLastButtonPress}.
\begin{procedure}{GetMouseState}
\Declaration
Procedure GetMouseState (Var x, y, buttons: Longint);
\Description
\procedure{GetMouseState}{(Var x, y, buttons: Longint)}{
\var{GetMouseState} Returns information on the current mouse position
and which buttons are currently pressed.
\var{x} and \var{y} return the mouse cursor coordinates in pixels.
\var{Buttons} is a bitmask. Check the example program to see how you can get the
necessary information from it.
}{None.}{\seef{LPressed}, \seef{MPressed}, \seef{RPressed},
\seep{SetMousePos}}
\Errors
None.
\SeeAlso
\seef{LPressed}, \seef{MPressed}, \seef{RPressed},
\seep{SetMousePos}
\end{procedure}
\latex{\inputlisting{mouseex/mouse3.pp}}
\html{\input{mouseex/mouse3.tex}}
\begin{procedure}{HideMouse}
\Declaration
Procedure HideMouse ;
\Description
\Procedure{HideMouse}{
\var{HideMouse} makes the mouse cursor invisible.
Multiple calls to HideMouse will require just as many calls to ShowMouse to
make the mouse cursor again visible.
}{None.}{\seep{ShowMouse}, \seep{SetMouseHideWindow}}
\Errors
None.
\SeeAlso
\seep{ShowMouse}, \seep{SetMouseHideWindow}
\end{procedure}
For an example, see \seep{ShowMouse}.
\begin{procedure}{InitMouse}
\Declaration
Procedure InitMouse ;
\Description
\Procedure{InitMouse}{
\var{InitMouse}
Initializes the mouse driver sets the variable \var{MouseFound} depending on
whether or not a mouse is found.
This is Automatically called at the start of your program.
You should never have to call it, unless you want to reset everything to
its default values.
}{None.}{\var{MouseFound} variable.}
\Errors
None.
\SeeAlso
\var{MouseFound} variable.
\end{procedure}
\latex{\inputlisting{mouseex/mouse1.pp}}
\html{\input{mouseex/mouse1.tex}}
\begin{function}{LPressed}
\Declaration
Function LPressed : Boolean;
\Function{LPressed}{Boolean}{
\Description
\var{LPressed} returns \var{True} if the left mouse button is pressed.
This is simply a wrapper for the GetMouseState procedure.
}{None.}{\seep{GetMouseState}, \seef{MPressed}, \seef{RPressed}}
\Errors
None.
\SeeAlso
\seep{GetMouseState}, \seef{MPressed}, \seef{RPressed}
\end{function}
For an example, see \seep{GetMouseState}.
\begin{function}{MPressed}
\Declaration
Function MPressed : Boolean;
\Description
\Function{MPressed}{Boolean}{
\var{MPressed} returns \var{True} if the middle mouse button is pressed.
This is simply a wrapper for the GetMouseState procedure.
}{None.}{\seep{GetMouseState}, \seef{LPressed}, \seef{RPressed}}
\Errors
None.
\SeeAlso
\seep{GetMouseState}, \seef{LPressed}, \seef{RPressed}
\end{function}
For an example, see \seep{GetMouseState}.
\begin{function}{RPressed}
\Declaration
Function RPressed : Boolean;
\Description
\Function{RPressed}{Boolean}{
\var{RPressed} returns \var{True} if the right mouse button is pressed.
This is simply a wrapper for the GetMouseState procedure.
}{None.}{\seep{GetMouseState}, \seef{LPressed}, \seef{MPressed}}
\Errors
None.
\SeeAlso
\seep{GetMouseState}, \seef{LPressed}, \seef{MPressed}
\end{function}
For an example, see \seep{GetMouseState}.
\begin{procedure}{SetMouseAscii}
\Declaration
Procedure SetMouseAscii (Ascii: Byte);
\Description
\procedure{SetMouseAscii}{(Ascii: Byte)}{
\var{SetMouseAscii}
sets the \var{Ascii} value of the character that depicts the mouse cursor in
text mode.
The difference between this one and \seep{SetMouseShape}, is that the foreground
and background colors stay the same and that the Ascii code you enter is the
character that you will get on screen; there's no XOR'ing.
}{None}{\seep{SetMouseShape}}
\Errors
None
\SeeAlso
\seep{SetMouseShape}
\end{procedure}
\latex{\inputlisting{mouseex/mouse8.pp}}
\html{\input{mouseex/mouse8.tex}}
\begin{procedure}{SetMouseHideWindow}
\Declaration
Procedure SetMouseHideWindow (xmin,ymin,xmax,ymax: Longint);
\Description
\procedure{SetMouseHideWindow}{(xmin,ymin,xmax,ymax: Longint)}{
\var{SetMouseHideWindow}
defines a rectangle on screen with top-left corner at (\var{xmin,ymin}) and
botto-right corner at (\var{xmax,ymax}),which causes the mouse cursor to be
turned off when it is moved into it.
When the mouse is moved into the specified region, it is turned off until you
call \var{ShowMouse} again. However, once you've called \seep{ShowMouse}, you'll have to
call \var{SetMouseHideWindow} again to redefine the hide window...
This may be annoying, but it's the way it's implemented in the mouse driver.
While \var{xmin, ymin, xmax} and \var{ymax} are Longint parameters,
only the lower 16 bits are used.
}{None.}{\seep{ShowMouse}, \seep{HideMouse}}
\Errors
None.
\SeeAlso
\seep{ShowMouse}, \seep{HideMouse}
\end{procedure}
\latex{nputlisting{mouseex/mouse9.pp}}
\html{\input{mouseex/mouse9.tex}}
\begin{procedure}{SetMousePos}
\Declaration
Procedure SetMousePos (x,y:Longint);
\Description
\procedure{SetMousePos}{(x,y:Longint)}{
\var{SetMosusePos} sets the position of the mouse cursor on the screen.
\var{x} is the horizontal position in pixels, \var{y} the vertical position
in pixels. The upper-left hand corner of the screen is the origin.
While \var{x} and \var{y} are longints, only the lower 16 bits are used.
}{None.}{\seep{GetMouseState}}
\Errors
None.
\SeeAlso
\seep{GetMouseState}
\end{procedure}
\latex{\inputlisting{mouseex/mouse4.pp}}
\html{\input{mouseex/mouse4.tex}}
\begin{procedure}{SetMouseShape}
\Declaration
Procedure SetMouseShape (ForeColor,BackColor,Ascii: Byte);
\Description
\procedure{SetMouseShape}{(ForeColor,BackColor,Ascii: Byte)}{
\var{SetMouseShape}
defines how the mouse cursor looks in textmode
The character and its attributes that are on the mouse cursor's position on
screen are XOR'ed with resp. \var{ForeColor}, \var{BackColor} and
\var{Ascii}. Set them all to 0 for a "transparent" cursor.
}{None.}{\seep{SetMouseAscii}}
\Errors
None.
\SeeAlso
\seep{SetMouseAscii}
\end{procedure}
\latex{\inputlisting{mouseex/mouse7.pp}}
\html{\input{mouseex/mouse7.tex}}
\begin{procedure}{SetMouseSpeed}
\Declaration
Procedure SetMouseSpeed (Horizontal, Vertical: Longint);
\Description
\procedure{SetMouseSpeed}{(Horizontal, Vertical: Longint)}{
\var{SetMouseSpeed} sets the mouse speed in mickeys per 8 pixels.
A mickey is the smallest measurement unit handled by a mouse. With this
procedure you can set how many mickeys the mouse should move to move the
cursor 8 pixels horizontally of vertically. The default values are 8 for
horizontal and 16 for vertical movement.
While this procedure accepts longint parameters, only the low 16 bits are
actually used.
}{None.}{}
\Errors
None.
\SeeAlso
\end{procedure}
\latex{\inputlisting{mouseex/mouse10.pp}}
\html{\input{mouseex/mouse10.tex}}
\begin{procedure}{SetMouseWindow}
\Declaration
Procedure SetMouseWindow (xmin,ymin,xmax,ymax: Longint);
\procedure{SetMouseWindow}{(xmin,ymin,xmax,ymax: Longint)}{
\Description
\var{SetMousWindow}
defines a rectangle on screen with top-left corner at (\var{xmin,ymin}) and
botto-right corner at (\var{xmax,ymax}), out of which the mouse
cursor can't move.
This procedure is simply a wrapper for the \seep{SetMouseXRange} and
\seep{SetMouseYRange} procedures.
While \var{xmin, ymin, xmax} and \var{ymax} are Longint parameters,
only the lower 16 bits are used.
}{None.}{\seep{SetMouseXRange}, \seep{SetMouseYRange}}
\Errors
None.
\SeeAlso
\seep{SetMouseXRange}, \seep{SetMouseYRange}
\end{procedure}
For an example, see \seep{SetMouseXRange}.
\begin{procedure}{SetMouseXRange}
\Declaration
Procedure SetMouseXRange (Min, Max: Longint);
\procedure{SetMouseXRange}{(Min, Max: Longint)}{
\Description
\var{SetMouseXRange}
sets the minimum (\var{Min}) and maximum (\var{Max}) horizontal coordinates in between which the
mouse cursor can move.
While \var{Min} and \var{Max} are Longint parameters, only the lower 16 bits
are used.
}{None.}{\seep{SetMouseYRange}, \seep{SetMouseWindow}}
\Errors
None.
\SeeAlso
\seep{SetMouseYRange}, \seep{SetMouseWindow}
\end{procedure}
\latex{\inputlisting{mouseex/mouse6.pp}}
\html{\input{mouseex/mouse6.tex}}
\begin{procedure}{SetMouseYRange}
\Declaration
Procedure SetMouseYRange (Min, Max: Longint);
\Description
\procedure{SetMouseYRange}{(Min, Max: Longint)}{
\var{SetMouseYRange}
sets the minimum (\var{Min}) and maximum (\var{Max}) vertical coordinates in between which the
mouse cursor can move.
While \var{Min} and \var{Max} are Longint parameters, only the lower 16 bits
are used.
}{None.}{\seep{SetMouseXRange}, \seep{SetMouseWindow}}
\Errors
None.
\SeeAlso
\seep{SetMouseXRange}, \seep{SetMouseWindow}
\end{procedure}
For an example, see \seep{SetMouseXRange}.
\begin{procedure}{ShowMouse}
\Declaration
Procedure ShowMouse ;
\Description
\Procedure{ShowMouse}{
\var{ShowMouse} makes the mouse cursor visible.
At the start of your progam, the mouse is invisible.
}{None.}{\seep{HideMouse},\seep{SetMouseHideWindow}}
\Errors
None.
\SeeAlso
\seep{HideMouse},\seep{SetMouseHideWindow}
\end{procedure}
\latex{\inputlisting{mouseex/mouse2.pp}}
\html{\input{mouseex/mouse2.tex}}

20
docs/printer.tex
View File

@ -23,14 +23,12 @@ 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. Its basic functionality
is the same for both systems.
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
@ -40,8 +38,12 @@ var
\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}
\procedure {AssignLst}{ ( Var F : text; ToFile : string[255])}
{ \linux only. \\
\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,
@ -55,9 +57,11 @@ You can change this behaviour at compile time, setting the DefFile constant.
deleted.
(useful for opening /dev/printer or for later printing)
\end{itemize}
}
{ Errors are reported in Linuxerror.}
{\seem{lpr}{1}}
\Errors
Errors are reported in Linuxerror.
\SeeAlso
\seem{lpr}{1}
\end{procedure}
\latex{\inputlisting{printex/printex.pp}}
\html{\input{printex/printex.tex}}
\html{\input{printex/printex.tex}}

384
docs/sockets.tex
View File

@ -21,14 +21,12 @@
\chapter{The SOCKETS unit.}
This chapter describes the SOCKETS unit for Free Pascal.
it was written for \linux by Micha\"el Van Canneyt.
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.
@ -79,12 +77,10 @@ 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;
@ -96,20 +92,22 @@ 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;
\function{Accept}{(Sock:Longint;Var Addr;Var Addrlen:Longint)}{Longint}
{\var{Accept} accepts a connection from a socket \var{Sock}, which was
\Description
\var{Accept} accepts a connection from a socket \var{Sock}, which was
listening for a connection. The accepted 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 are reported in \var{SocketError}, and include the following:
\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.
@ -118,57 +116,75 @@ operation.
\item[SYS\_EFAULT] \var{Addr} points outside your address space.
\item[SYS\_EWOULDBLOCK] The requested operation would block the process.
\end{description}
}
{\seef{Listen}, \seef{Connect}}
\SeeAlso
\seef{Listen}, \seef{Connect}
\end{function}
\latex{\inputlisting{sockex/sock_svr.pp}}
\html{\input{sockex/sock_svr.tex}}
\begin{functionl}{Accept}{AltAAccept}
\Declaration
Function Accept (Sock:longint;var addr:string;var SockIn,SockOut:text) : Boolean;
\functionl{Accept}{AltAAccept}{(Sock:longint;var addr:string;var SockIn,SockOut:text)}{Boolean}
{ This is an alternate form of the \seef{Accept} command. It is equivalent
\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.
}
{The errors are those of \seef{Accept}.}
{\seef{Accept}}
\functionl{Accept}{AltBAccept}{(Sock:longint;var addr:string;var SockIn,SockOut:File)}{Boolean}
{ This is an alternate form of the \seef{Accept} command.
\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.
}
{The errors are those of \seef{Accept}.}
{\seef{Accept}}
\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;
\functionl{Accept}{AltCAccept}{(Sock:longint;var addr:TInetSockAddr;var SockIn,SockOut:File)}{Boolean}
{ This is an alternate form of the \seef{Accept} command.
\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.
}
{The errors are those of \seef{Accept}.}
{\seef{Accept}}
\function{Bind}{(Sock:Longint;Var Addr;AddrLen:Longint)}{Boolean}
{\var{Bind} binds the socket \var{Sock} to address \var{Addr}. \var{Addr}
\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 are returned in \var{SocketError} and include the following:
\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,
@ -176,76 +192,108 @@ not.
open it.
\end{description}
More arrors can be found in the Unix man pages.
}{\seef{Socket}}
\functionl{Bind}{AltBind}{(Sock:longint;const addr:string)}{boolean}
{This is an alternate form of the \var{Bind} command.
\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 are those of the regular \seef{Bind} command.}
{\seef{Bind}}
\function{Connect}{(Sock:Longint;Var Addr;Addrlen:Longint)}{Boolean}
{\var{Connect} opens a connection to a peer, whose address is described by
\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) : Boolean;
\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}.
}
{Errors are reported in \var{SocketError}.}
{\seef{Listen}, \seef{Bind},\seef{Accept}}
\Errors
Errors are reported in \var{SocketError}.
\SeeAlso
\seef{Listen}, \seef{Bind},\seef{Accept}
\end{function}
\latex{\inputlisting{sockex/sock_cli.pp}}
\html{\input{sockex/sock_cli.tex}}
\begin{functionl}{Connect}{AltAConnect}
\Declaration
Function Connect (Sock:longint;const addr:string;var SockIn,SockOut:text) : Boolean;
\functionl{Connect}{AltAConnect}{(Sock:longint;const addr:string;var SockIn,SockOut:text)}{Boolean}
{ This is an alternate form of the \seef{Connect} command.
\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.
}{The errors are those of \seef{Connect}.}
{\seef{Connect}}
\functionl{Connect}{AltBConnect}{(Sock:longint;const addr:string;var SockIn,SockOut:file)}{Boolean}
{ This is an alternate form of the \seef{Connect} command. The parameter
\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.
}{The errors are those of \seef{Connect}.}
{\seef{Connect}}
\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;
\functionl{Connect}{AltCConnect}{(Sock:longint;const addr: TInetSockAddr;var SockIn,SockOut:file)}{Boolean}
{ This is another alternate form of the \seef{Connect} command.
\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.
}{The errors are those of \seef{Connect}.}
{\seef{Connect}}
\Errors
The errors are those of \seef{Connect}.
\SeeAlso
\seef{Connect}
\end{functionl}
\latex{\inputlisting{sockex/pfinger.pp}}
\html{\input{sockex/pfinger.tex}}
\begin{function}{GetPeerName}
\Declaration
Function GetPeerName (Sock:Longint;Var Addr;Var Addrlen:Longint) : Longint;
\function{GetPeerName}{(Sock:Longint;Var Addr;Var Addrlen:Longint)}{Longint}
{\var{GetPeerName} returns the name of the entity connected to the
\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 are reported in \var{SocketError}, and include the following:
\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
@ -254,15 +302,22 @@ operation.
\item[SYS\_EFAULT] \var{Addr} points outside your address space.
\item[SYS\_ENOTCONN] The socket isn't connected.
\end{description}
}{\seef{Connect}, \seef{Socket}, \seem{connect}{2}}
\function{GetSocketName}{(Sock:Longint;Var Addr;Var Addrlen:Longint)}{Longint}
{\var{GetSockName} returns the current name of the specified socket
\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 are reported in \var{SocketError}, and include the following:
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
@ -270,11 +325,16 @@ operation.
\item[SYS\_ENOTSOCK] The descriptor is not a socket.
\item[SYS\_EFAULT] \var{Addr} points outside your address space.
\end{description}
}{\seef{Bind}}
\SeeAlso
\seef{Bind}
\end{function}
\begin{function}{GetSocketOptions}
\Declaration
Function GetSocketOptions (Sock,Level,OptName:Longint;Var OptVal;optlen:longint) : Longint;
\function{GetSocketOptions}{(Sock,Level,OptName:Longint;Var OptVal;optlen:longint)}{Longint}
{\var{GetSocketOptions} gets the connection options for socket \var{Sock}.
\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}
@ -283,47 +343,58 @@ which can be one of the following:
which should interprete the option.
\end{description}
For more information on this call, refer to the unix manual page \seem{getsockopt}{2}.
}
{Errors are reported in \var{SocketError}, and include the following:
\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}
}
{\seef{GetSocketOptions}}
\function{Listen}{(Sock,MaxConnect:Longint)}{Boolean}
{\var{Listen} listens for up to \var{MaxConnect} connections from socket
\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 are reported in \var{SocketError}, and include the following:
\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}
}{\seef{Socket}, \seef{Bind}, \seef{Connect}}
\function{Recv}{(Sock:Longint;Var Addr;AddrLen,Flags:Longint)}{Longint}
{\var{Recv} reads at most \var{Addrlen} bytes from socket \var{Sock} into
\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 are reported in \var{SocketError}, and include the following:
-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.
@ -333,22 +404,27 @@ The functions returns the number of bytes actually read from the socket, or
\item[SYS\_EWOULDBLOCK] The requested operation would block the process.
\item[SYS\_ENOBUFS] The system doesn't have enough free buffers available.
\end{description}
}{\seef{Send}}
\function{Send}{(Sock:Longint;Var Addr;AddrLen,Flags:Longint)}{Longint}
{\var{Send} sends \var{AddrLen} bytes starting from address \var{Addr}
\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 are reported in \var{SocketError}, and include the following:
\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.
@ -357,10 +433,16 @@ error occurred.
\item[SYS\_EWOULDBLOCK] The requested operation would block the process.
\item[SYS\_ENOBUFS] The system doesn't have enough free buffers available.
\end{description}
}{\seef{Recv}, \seem{send}{2}}
\function{SetSocketOptions}{(Sock,Level,OptName:Longint;Var OptVal;optlen:longint)}{Longint}
{\var{SetSocketOptions} sets the connection options for socket \var{Sock}.
\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}
@ -369,18 +451,24 @@ which can be one of the following:
which should interprete the option.
\end{description}
For more information on this call, refer to the unix manual page \seem{setsockopt}{2}.
}
{Errors are reported in \var{SocketError}, and include the following:
\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}
}
{\seef{GetSocketOptions}}
\function{Shutdown}{(Sock:Longint;How:Longint)}{Longint}
{\var{ShutDown} closes one end of a full duplex socket connection, described
\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}
@ -388,44 +476,59 @@ and can be one of the following:
\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.
}
{\var{SocketError} is used to report errors, and includes the following:
\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}
}{\seef{Socket}, \seef{Connect}}
\procedure{Sock2File}{(Sock:Longint;Var SockIn,SockOut:File)}
{\var{Sock2File} transforms a socket \var{Sock} into 2 Pascal file
\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}).}
{None.}
{\seef{Socket}, \seep{Sock2Text}}
(\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);
\procedure{Sock2Text}{(Sock:Longint;Var SockIn,SockOut: Text)}
{\var{Sock2Text} transforms a socket \var{Sock} into 2 Pascal file
\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}).}
{None.}
{\seef{Socket}, \seep{Sock2File}}
(\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;
\function{Socket}{(Domain,SocketType,Protocol:Longint)}{Longint}
{\var{Socket} creates a new socket in domain \var{Domain}, from type
\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 are returned in \var{SocketError}, and include the follwing:
\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
@ -441,21 +544,26 @@ The system file table is full.
Insufficient buffer space is available. The
socket cannot be created until sufficient
resources are freed.
\end{description}}
{\seef{SocketPair}, \seem{socket}{2}}
\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;
\function{SocketPair}{(Domain,SocketType,Protocol:Longint;var Pair:TSockArray)}{Longint}
{\var{SocketPair} creates 2 sockets in domain \var{Domain}, from type
\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 are reported in \var{SocketError}, and are the same as in \seef{Socket}}
\procedure{Str2UnixSockAddr}{(const addr:string;var t:TUnixSockAddr;var len:longint)}
\Errors
Errors are reported in \var{SocketError}, and are the same as in \seef{Socket}
\SeeAlso
Str2UnixSockAddr{(const addr:string;var t:TUnixSockAddr;var len:longint)}
\end{function}
{\var{Str2UnixSockAddr} transforms a Unix socket address in a string to a
\var{TUnixSockAddr} sturcture which can be passed to the \seef{Bind} call.
}

319
docs/strings.tex
View File

@ -21,253 +21,376 @@
\chapter{The STRINGS unit.}
This chapter describes the \var{STRINGS} unit for
\fpc.
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{procedure}{StrAlloc}
\Declaration
Procedure StrAlloc (Len : Longint);
\Description
PChar
\Errors
\procedure{StrAlloc}{(Len : Longint)}{PChar}
{
\var{StrAlloc} reserves memory on the heap for a string with length \var{Len},
terminating \var{\#0} included, and returns a pointer to it.
}
For an example, see \seef{StrPCopy}.
\SeeAlso
StrPCopy.
\end{procedure}
\begin{function}{StrCat}
\Declaration
Function StrCat (Dest,Source : PChar) : PChar;
\Description
\function{StrCat}{(Dest,Source : PChar)}{PChar}
{
Attaches \var{Source} to \var{Dest} and returns \var{Dest}.
}
{No length checking is performed.}
{\seem{Concat}{}}
\Errors
No length checking is performed.
\SeeAlso
\seem{Concat}{}
\end{function}
\latex{\inputlisting{stringex/ex11.pp}}
\html{\input{stringex/ex11.tex}}
\begin{function}{StrComp}
\Declaration
Function StrComp (S1,S2 : PChar) : Longint;
\Description
\function{StrComp}{(S1,S2 : PChar)}{Longint}
{
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}
}
{None.}{\seef{StrLComp}, \seef{StrIComp}, \seef{StrLIComp}}
\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;
\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.
}
{No length checking is performed.}{ \seef{StrPCopy}, \seef{StrLCopy}, \seef{StrECopy}}
\Errors
No length checking is performed.
\SeeAlso
\seef{StrPCopy}, \seef{StrLCopy}, \seef{StrECopy}
\end{function}
\latex{\inputlisting{stringex/ex4.pp}}
\html{\input{stringex/ex4.tex}}
\begin{procedure}{StrDispose}
\Declaration
Procedure StrDispose (P : PChar);
\Description
\procedure{StrDispose}{(P : PChar)}
{
Removes the string in \var{P} from the heap and releases the memory.
}
{None.}{\seem{Dispose}{}, \seef{StrNew}}
\Errors
None.
\SeeAlso
\seem{Dispose}{}, \seef{StrNew}
\end{procedure}
\latex{\inputlisting{stringex/ex17.pp}}
\html{\input{stringex/ex17.tex}}
\begin{function}{StrECopy}
\Declaration
Function StrECopy (Dest,Source : PChar) : PChar;
\Description
\function{StrECopy}{(Dest,Source : PChar)}{PChar}
{
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.
}
{No length checking is performed.}
{\seef{StrLCopy}, \seef{StrCopy}}
\Errors
No length checking is performed.
\SeeAlso
\seef{StrLCopy}, \seef{StrCopy}
\end{function}
\latex{\inputlisting{stringex/ex6.pp}}
\html{\input{stringex/ex6.tex}}
\begin{function}{StrEnd}
\Declaration
Function StrEnd (P : PChar) : PChar;
\Description
\function{StrEnd}{(P : PChar)}{PChar}
{
Returns a pointer to the end of \var{P}. (i.e. to the terminating
null-character.
}
{None.}{\seef{StrLen}}
\Errors
None.
\SeeAlso
\seef{StrLen}
\end{function}
\latex{\inputlisting{stringex/ex7.pp}}
\html{\input{stringex/ex7.tex}}
\begin{function}{StrIComp}
\Declaration
Function StrIComp (S1,S2 : PChar) : Longint;
\Description
\function{StrIComp}{(S1,S2 : PChar)}{Longint}
{
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}
}
{None.}{\seef{StrLComp}, \seef{StrComp}, \seef{StrLIComp}}
\Errors
None.
\SeeAlso
\seef{StrLComp}, \seef{StrComp}, \seef{StrLIComp}
\end{function}
\latex{\inputlisting{stringex/ex8.pp}}
\html{\input{stringex/ex8.tex}}
\begin{function}{StrLCat}
\Declaration
Function StrLCat (Dest,Source : PChar; MaxLen : Longint) : PChar;
\Description
\function{StrLCat}{(Dest,Source : PChar; MaxLen : Longint)}{PChar}
{
Adds \var{MaxLen} characters from \var{Source} to \var{Dest}, and adds a
terminating null-character. Returns \var{Dest}.
}
{None.}{\seef{StrCat}}
\Errors
None.
\SeeAlso
\seef{StrCat}
\end{function}
\latex{\inputlisting{stringex/ex12.pp}}
\html{\input{stringex/ex12.tex}}
\begin{function}{StrLComp}
\Declaration
Function StrLComp (S1,S2 : PChar; L : Longint) : Longint;
\Description
\function{StrLComp}{(S1,S2 : PChar; L : Longint)}{Longint}
{
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}
}
{None.}{\seef{StrComp}, \seef{StrIComp}, \seef{StrLIComp}}
\Errors
None.
\SeeAlso
\seef{StrComp}, \seef{StrIComp}, \seef{StrLIComp}
\end{function}
\latex{\inputlisting{stringex/ex8.pp}}
\html{\input{stringex/ex8.tex}}
\begin{function}{StrLCopy}
\Declaration
Function StrLCopy (Dest,Source : PChar; MaxLen : Longint) : PChar;
\Description
\function{StrLCopy}{(Dest,Source : PChar; MaxLen : Longint)}{PChar}
{
Copies \var{MaxLen} characters from \var{Source} to \var{Dest}, and makes
\var{Dest} a null terminated string.
}
{No length checking is performed.}
{\seef{StrCopy}, \seef{StrECopy}}
\Errors
No length checking is performed.
\SeeAlso
\seef{StrCopy}, \seef{StrECopy}
\end{function}
\latex{\inputlisting{stringex/ex5.pp}}
\html{\input{stringex/ex5.tex}}
\begin{function}{StrLen}
\Declaration
Function StrLen (p : PChar) : Longint;
\Description
\function{StrLen}{(p : PChar)}{Longint}
{
Returns the length of the null-terminated string \var{P}.
}
{None.}{\seem{Length}{}}
\Errors
None.
\SeeAlso
\seem{Length}{}
\end{function}
\latex{\inputlisting{stringex/ex1.pp}}
\html{\input{stringex/ex1.tex}}
\begin{function}{StrLIComp}
\Declaration
Function StrLIComp (S1,S2 : PChar; L : Longint) : Longint;
\Description
\function{StrLIComp}{(S1,S2 : PChar; L : Longint)}{Longint}
{
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}
}
{None.}{\seef{StrLComp}, \seef{StrComp}, \seef{StrIComp}}
\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
\function{StrLower}{(P : PChar)}{PChar}
{
Converts \var{P} to an all-lowercase string. Returns \var{P}.
}
{None.}{\seem{Upcase}{}, \seef{StrUpper}}
\Errors
None.
\SeeAlso
\seem{Upcase}{}, \seef{StrUpper}
\end{function}
\latex{\inputlisting{stringex/ex14.pp}}
\html{\input{stringex/ex14.tex}}
\begin{function}{StrMove}
\Declaration
Function StrMove (Dest,Source : PChar; MaxLen : Longint) : PChar;
\Description
\function{StrMove}{(Dest,Source : PChar; MaxLen : Longint)}{PChar}
{
Copies \var{MaxLen} characters from \var{Source} to \var{Dest}. No
terminating null-character is copied.
Returns \var {Dest}.
}
{None.}{\seef{StrLCopy}, \seef{StrCopy}}
\Errors
None.
\SeeAlso
\seef{StrLCopy}, \seef{StrCopy}
\end{function}
\latex{\inputlisting{stringex/ex10.pp}}
\html{\input{stringex/ex10.tex}}
\begin{function}{StrNew}
\Declaration
Function StrNew (P : PChar) : PChar;
\Description
\function{StrNew}{(P : PChar)}{PChar}
{
Copies \var{P} to the Heap, and returns a pointer to the copy.
}
{Returns \var{Nil} if no memory was available for the copy.}
{\seem{New}{}, \seef{StrCopy}, \seep{StrDispose}}
\Errors
Returns \var{Nil} if no memory was available for the copy.
\SeeAlso
\seem{New}{}, \seef{StrCopy}, \seep{StrDispose}
\end{function}
\latex{\inputlisting{stringex/ex16.pp}}
\html{\input{stringex/ex16.tex}}
\begin{function}{StrPas}
\Declaration
Function StrPas (P : PChar) : String;
\Description
\function {StrPas}{(P : PChar)}{String}
{
Converts a null terminated string in \var{P} to a Pascal string, and returns
this string. The string is truncated at 255 characters.
}
{None.}{ \seef{StrPCopy}}
\Errors
None.
\SeeAlso
\seef{StrPCopy}
\end{function}
\latex{\inputlisting{stringex/ex3.pp}}
\html{\input{stringex/ex3.tex}}
\begin{function}{StrPCopy}
\Declaration
Function StrPCopy (Dest : PChar; Const Source : String) : PChar;
\Description
\function{StrPCopy}{(Dest : PChar; Const Source : String)}{PChar}
{
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.
}
{No length checking is performed.}{ \seef{StrPas}}
\Errors
No length checking is performed.
\SeeAlso
\seef{StrPas}
\end{function}
\latex{\inputlisting{stringex/ex2.pp}}
\html{\input{stringex/ex2.tex}}
\begin{function}{StrPos}
\Declaration
Function StrPos (S1,S2 : PChar) : PChar;
\Description
\function{StrPos}{(S1,S2 : PChar)}{PChar}
{
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}.
}
{None.}{\seem{Pos}{}, \seef{StrScan}, \seef{StrRScan}}
\Errors
None.
\SeeAlso
\seem{Pos}{}, \seef{StrScan}, \seef{StrRScan}
\end{function}
\latex{\inputlisting{stringex/ex15.pp}}
\html{\input{stringex/ex15.tex}}
\begin{function}{StrRScan}
\Declaration
Function StrRScan (P : PChar; C : Char) : PChar;
\Description
\function{StrRScan}{(P : PChar; C : Char)}{PChar}
{
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}.
}
{None.}{\seem{Pos}{}, \seef{StrScan}, \seef{StrPos}}
\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
\function{StrScan}{(P : PChar; C : Char)}{PChar}
{
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}.
}
{None.}{\seem{Pos}{}, \seef{StrRScan}, \seef{StrPos}}
\Errors
None.
\SeeAlso
\seem{Pos}{}, \seef{StrRScan}, \seef{StrPos}
\end{function}
\latex{\inputlisting{stringex/ex13.pp}}
\html{\input{stringex/ex13.tex}}
\begin{function}{StrUpper}
\Declaration
Function StrUpper (P : PChar) : PChar;
\Description
\function{StrUpper}{(P : PChar)}{PChar}
{
Converts \var{P} to an all-uppercase string. Returns \var{P}.
}
{None.}{\seem{Upcase}{}, \seef{StrLower}}
\Errors
None.
\SeeAlso
\seem{Upcase}{}, \seef{StrLower}
\end{function}
For an example, see \seef{StrLower}