paweld/fpc
1
0
Fork 0
mirror of https://gitlab.com/freepascal.org/fpc/source.git synced 2025-04-23 07:09:42 +02:00
Code Issues Packages Projects Releases Wiki Activity

+ sorted entries

Browse Source
This commit is contained in:
michael 1998-07-16 17:48:19 +00:00
parent 8fd5dde94c
commit 35c2815722
6 changed files with 737 additions and 701 deletions

3
docs/Makefile
View File

@ -149,7 +149,7 @@ clean:
-$(MAKE) -C printex clean
-$(MAKE) -C stringex clean
-$(MAKE) -C sockex clean
-$(MAKE) -C mouseex clean
unitex.chk:
$(MAKE) -C crtex tex
$(MAKE) -C linuxex tex
@ -158,6 +158,7 @@ unitex.chk:
$(MAKE) -C printex tex
$(MAKE) -C stringex tex
$(MAKE) -C sockex tex
$(MAKE) -C mouseex tex
touch unitex.chk
refex.chk:

216
docs/crt.tex
View File

@ -107,6 +107,7 @@ var lastmode : Word;
\end{verbatim}
\section{Procedures and Functions}
\procedure{AssignCrt}{(Var F: Text)}
{
Assigns a file F to the console. Everything written to the file F goes to
@ -117,6 +118,37 @@ to the window instead.
\input{crtex/ex1.tex}
\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}}
\input{crtex/ex9.tex}
\procedure {ClrScr}{}
{ 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} }
\input{crtex/ex8.tex}
\Procedure{CursorOff}{Switches the cursor off (i.e. the cursor is no
longer visible).
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 a approximation, and may be off a lot, if system load is high.}
@ -124,25 +156,22 @@ seconds is a approximation, and may be off a lot, if system load is high.}
\input{crtex/ex15.tex}
\procedure {TextColor}{(CL: Byte)}
{
TextColor sets the foreground color to \var{CL}. \var{CL} can be one of the
predefined color constants.
\Procedure {DelLine}
{ 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}}
\input{crtex/ex11.tex}
\procedure {GotoXY}{(X: Byte; Y: Byte)}
{ 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.}{ \seep{TextBackground}, \seep{HighVideo}, \seep{LowVideo},
\seep{NormVideo}}
{None.}{ \seef{WhereX}, \seef{WhereY}, \seep{Window} }
\input{crtex/ex12.tex}
\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}}
\input{crtex/ex13.tex}
\input{crtex/ex6.tex}
\procedure {HighVideo}{}
{ HighVideo switches the output to highlighted text. (It sets the high
@ -153,6 +182,26 @@ intensity bit of the video attribute)
\input{crtex/ex14.tex}
\procedure {InsLine}{}
{ 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}}
\input{crtex/ex10.tex}
\Function {KeyPressed}{Boolean}
{ 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} 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}}
\input{crtex/ex2.tex}
\Procedure {LowVideo}
{ LowVideo switches the output to non-highlighted text. (It clears the high
intensity bit of the video attribute)
@ -171,30 +220,52 @@ defaults are read from the cursor position at startup)
For an example, see \seep{HighVideo}
\Procedure{BigCursor}{Makes the cursor a big rectangle.
\Procedure{NoSound}{
Stops the speaker sound.
Not implemented on \linux.}
{None.}{\seep{CursorOn}, \seep{CursorOff}}
This is not supported in \linux}{None.}{\seep{Sound}}
\Procedure{CursorOn}{Switches the cursor on.
\input{crtex/ex16.tex}
Not implemented on \linux.}
{None.}{\seep{BigCursor}, \seep{CursorOff}}
\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.
\Procedure{CursorOff}{Switches the cursor off (i.e. the cursor is no
longer visible).
Not implemented on \linux.}
{None.}{\seep{CursorOn}, \seep{BigCursor}}
\procedure {GotoXY}{(X: Byte; Y: Byte)}
{ 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.
\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{WhereX}, \seef{WhereY}, \seep{Window} }
{None.}{\seef{KeyPressed}}
\input{crtex/ex6.tex}
\input{crtex/ex3.tex}
\procedure{Sound}{(hz : word)}
{ Sounds the speaker at a frequency of \var{hz}.
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}}
\input{crtex/ex13.tex}
\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}}
\input{crtex/ex12.tex}
\Function {WhereX}{Byte}
{
@ -232,15 +303,6 @@ are relative to the window's top left corner.
\input{crtex/ex5.tex}
\procedure {ClrScr}{}
{ 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} }
\input{crtex/ex8.tex}
%\procedure {ScrollWindow}{(X1,Y1,X2,Y2 : Byte; Count : Longint)}
%{ 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
@ -275,69 +337,3 @@ corner of the current window.}
%The memory pointed to by \var{P} is NOT freed.}{None}
%{\seef{SaveScreenRegion}, \seep{Window} }
\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}}
\input{crtex/ex9.tex}
\Procedure {DelLine}
{ 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}}
\input{crtex/ex11.tex}
\procedure {InsLine}{}
{ 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}}
\input{crtex/ex10.tex}
\Function {KeyPressed}{Boolean}
{ 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} 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}}
\input{crtex/ex2.tex}
\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}}
\input{crtex/ex3.tex}
\procedure{Sound}{(hz : word)}
{ Sounds the speaker at a frequency of \var{hz}.
This is not supported in \linux}{None.}{\seep{NoSound}}
\Procedure{NoSound}{
Stops the speaker sound.
This is not supported in \linux}{None.}{\seep{Sound}}
\input{crtex/ex16.tex}

62
docs/getopts.tex
View File

@ -70,35 +70,6 @@ messages.\\
\var{OptOpt:Char} \ In case of an error, contains the character causing the
error.
\section {Procedures and functions}
\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 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}}
\input{optex/optex.tex}
\function {GetLongOpts}{(Shortopts : String, LongOpts : POption; var Longint
: Integer )}{Char}
@ -132,4 +103,35 @@ Optional arguments can only be specified through the first method.
}
{ see \seef{Getopt}, \seem{getopt}{3}}
For an example, see \seef{Getopt}
For an example, see \seef{Getopt}
\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 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}}
\input{optex/optex.tex}

504
docs/go32.tex
View File

@ -240,109 +240,6 @@ Selector to the \dos memory. The whole \dos memory is mapped to a
single segment. This function will only work in DPMI mode.
\section{Functions and Procedures}
\procedure {Disable}{}{
Clears the interrupt flag with CLD and disables the interrupts.
}
{None.}{\seep{Enable}}
\par {\bf NOTE: }This
function works only in DPMI mode\par
\procedure{Enable}{}{
Sets the interrupt flag with STI and allows the processor to handle
interrupts.
}{None.}{\seep{Disable}}
\procedurel{get\_meminfo}{GetMeminfo}{(var meminfo : tmeminfo)}{
Returns the current state of memory allocation of the \dos extender.
\textbf{NOTE: }This procedure has nothing to do with the Pascal function
\var{maxavail} and \var{memavail}.}{None.}
{\htmlref{tmeminfo}{ty:tmeminfo}}
\procedurel{get\_pm\_interrupt}{GetPmInterrupt}{(vector : byte;var intaddr : tseginfo)}
{
Returns the address of the current protected mode handler for the interrupt
\var{vector}.}{None.}
{\seep{SetPmInterrupt},\htmlref{tseginfo}{ty:tseginfo}}
\functionl{get\_run\_mode}{GetRunMode}{}{word}{
This function returns the mode which the extender is currently running.
The function is mostly used to determine if DPMI is supported.
}{None.}
{\htmlref{rm}{co:rmmode}}
Example :
\begin{verbatim}
uses
go32;
begin
if get_run_mode=rm_dpmi then
writeln('DPMI available')
else
writeln('No DPMI available');
end.
\end{verbatim}
\functionl{get\_cs}{GetCs}{}{word}{Returns the value of the CS
register.}{None.}{\seef{GetDs},\seef{GetSs}}
\functionl{get\_ds}{GetDs}{}{word}{Returns the value of the DS
register.}{None.}{\seef{GetCs},\seef{GetSs}}
\functionl{get\_ss}{GetSs}{word}{Returns the value of the SS
register.}{None.}{\seef{GetDs},\seef{GetCs}}
\function{inportb}{(port : word)}{byte}{Reads a byte from the given I/O
port.}{None.}{\seep{outportb},\seef{inportw},\seef{inportl}}
\function{inportw}{(port : word)}{word}{Reads a word from the given I/O
port.}{None.}{\seep{outportw},\seef{inportb},\seef{inportl}}
\function{inportl}{(port : word)}{longint}{Reads a longint from the given I/O
port.}{None.}{\seep{outportl},\seef{inportw},\seef{inportb}}
\procedure{outportb}{(port : word;data : byte)}{Writes a byte to the
specified port.}{None.}{\seef{inportb},\seep{outportw},\seep{outportl}}
\procedure{outportw}{(port : word;data : word)}{Writes a word to the
specified port.}{None.}{\seef{inportw},\seep{outportb},\seep{outportl}}
\procedure{outportl}{(port : word;data : longint)}{Writes a longint to the
specified port.}{None.}{\seef{inportl},\seep{outportb},\seep{outportw}}
\procedure{realintr}{(intnr : word;var regs : trealregs)}{
\textbf {NOTE: }This procedure works only in DPMI mode.}
{None.}{}
\procedurel{seg\_fillchar}{SegFillChar}{(seg : word;ofs : longint;count : longint;c :
char)}
{Fills a memory area specified by a 48 bit pointer with the given number
of chars.
\textbf {NOTE:} Be careful using this function in non-DPMI mode.
}{None.}{\seep{SegFillWord}, \seep{SegMove}}
\procedurel {seg\_fillword}{SegFillWord}{(seg : word;ofs : longint;count : longint;w :
word)}{Fills a memory area specified by a 48 bit pointer with the given number
of words.
\textbf {NOTE:} Be careful using this function in non-DPMI mode.
}{None.}{\seep{SegFillChar}, \seep{SegMove}}
\procedurel{seg\_move}{SegMove}{(sseg : word;source : longint;dseg : word;dest : longint;count :
longint)}
{This procedure copies data when the source and destination are specified
by 48 bit pointers. For example, this function is used by the DPMI version
of \var{dosmemget} and \var{dosmemput}. }{The procedure checks only
for overlapping if source selector equals the destination selector.
Be also careful using this function in non-DPMI
mode.}{\seep{SegFillWord},\seep{SegFillChar}}
\procedurel{set\_pm\_interrupt}{SetPmInterrupt}{(vector : byte;const intaddr : tseginfo)}
{Sets a new protected mode handler for the interrupt \var{vector}.}
{None.}{\seep{GetPmInterrupt}, \htmlref{tseginfo}{ty:tseginfo}}
\functionl{Allocate\_Ldt\_Descriptors}{AllocateLdtDescriptors}{(Count :
word)}{word}
@ -408,148 +305,6 @@ end.
\end{verbatim}
\end{FPCList}
\procedurel{Free\_Ldt\_Descriptor}{FreeLdtDescriptor}{(Sel : word)}
{
\var{Free\_Ldt\_Descriptor} frees a previously allocated selector
with descriptor \var{Sel}
{\em Notes:}
\begin{itemize}
\item Only works with real DPMI.
\item After this call this selector is invalid and must not be used for any
memory operations anymore.
\item Each descriptor allocated with \var{allocate\_ltd\_descriptor} must be
freed
individually with this function, even if it was previously allocated as
a part of a contiguous array of descriptors.
\end{itemize}
}
{None.}
{\seef{AllocateLdtDescriptors}}
For an example, see \seef{AllocateLdtDescriptors}.
\functionl{Segment\_To\_Descriptor}{SegmentToDescriptor}{(Seg : Word)}{Word}
{\var{Segment\_To\_Descriptor} Maps a real mode segment (paragraph) address
(in \var{Seg}) onto an descriptor that can be used by a protected mode
program to access the same memory.
The function returns a selector to the DOS real-mode segment.
{\em Notes:}
\begin{itemize}
\item Only works with real DPMI.
\item The descriptors limit will be set to 64KB.
\item multiple calls to this function with the same segment address will
return the same selector.
\item Descriptors created by this function can never be modified or freed.
For this reason this function shouldn't be used too often. Programs
which need to examine various real mode addresses using the same
selector should use the function \var{allocate\_ldt\_descriptors} and change
the base address as necessary.
\end{itemize}
}
{None.}
{}
\begin{FPCList}
\item[Example]
\begin{verbatim}
uses go32;
var r : trealregs;
VGAsel : word;
begin
r.realeax := $13; realintr($10, r);
{ set VGA mode 13h }
VGASel := segment_to_descriptor($A000);
{...}
seg_fillchar(VGAsel, 100*320+6, 1, #15);
{ put a pixel at (6/100) in color 15 }
readln;
{...}
r.realeax := $3; realintr($10, r);
end.
\end{verbatim}
\end{FPCList}
\Functionl{Get\_Next\_Selector\_Increment\_Value}
{GetNextSelectorIncrementValue}{word}
{\var{Get\_Next\_Selector\_Increment\_Value} returns the selector increment
value when allocating multiple subsequent descriptors
The function \var{allocate\_ldt\_descriptors} can allocate an array of
contiguous descriptors, but only return the selector for the first. The
value returned by this function can be used to calculate the selectors
for subsequent descriptors in the array.
{\em Notes:}
\begin{itemize}
\item Only works under real DPMI.
\item the increment is always a power of 2.
\end{itemize}
}
{None.}
{\seef{AllocateLdtDescriptors}}
\functionl{Get\_Segment\_Base\_Address}{GetSegmentBaseAddress}{(Sel: word)}{Longint}
{
\var{Get\_Segment\_Base\_Address} returns the 32-bit linear base address
from the LDT descriptor for the specified segment (\var{Sel}).
{\em Notes:}
\begin{itemize}
\item Only works under real DPMI.
\end{itemize}
}
{None.}
{\seep{SetSegmentBaseAddress}}
\begin{FPCList}
\item[Example:]
\begin{verbatim}
uses go32;
begin
Writeln(get_segment_base_address(get_ds));
end.
\end{verbatim}
\end{FPCList}
\procedurel{Set\_Segment\_Base\_Address}{SetSegmentBaseAddress}
{(var Des : word;Sel : longint)}
{\var{{Set\_Segment\_Base\_Address}} sets the 32-bit linear base address
of the descriptor \var{Des} for the specified selector \var{Sel}.
{\em Notes:}
\begin{itemize}
\item only works under real DPMI
\end{itemize}
}
{None.}
{ \seef{AllocateLdtDescriptors}, \seep{SetSegmentLimit}}
For an example, see \seef{AllocateLdtDescriptors}.
\procedurel{Set\_Segment\_Limit}{SetSegmentLimit}{(Des : word;Len : longint)}
{\var{Set\_Segment\_Limit} sets the limit of the descriptor \var{Des}
to the specified length \var{Len}
{\em Notes:}
\begin{itemize}
\item Only works under real DPMI.
\item The new limit is the byte length of the segment-1.
\item Segment limits bigger than or equal to 1MB must be page aligned, they
must have the lower 12 bits set.
\end{itemize}
}
{None}
{ \seep{SetSegmentBaseAddress}, \seef{AllocateLdtDescriptors}}
For an example, see \seef{AllocateLdtDescriptors}.
\functionl{Create\_Code\_Segment\_Alias\_Descriptor}
{CreateCodeSegmentAliasDescriptor}{(Des : Word)}{Word}
{\var{Create\_Code\_Segment\_Alias\_Descriptor}
@ -583,6 +338,52 @@ end.
\end{verbatim}
\end{FPCList}
\procedure {Disable}{}{
Clears the interrupt flag with CLD and disables the interrupts.
}
{None.}{\seep{Enable}}
\par {\bf NOTE: }This
function works only in DPMI mode\par
\procedure{Enable}{}{
Sets the interrupt flag with STI and allows the processor to handle
interrupts.
}{None.}{\seep{Disable}}
\procedurel{Free\_Ldt\_Descriptor}{FreeLdtDescriptor}{(Sel : word)}
{
\var{Free\_Ldt\_Descriptor} frees a previously allocated selector
with descriptor \var{Sel}
{\em Notes:}
\begin{itemize}
\item Only works with real DPMI.
\item After this call this selector is invalid and must not be used for any
memory operations anymore.
\item Each descriptor allocated with \var{allocate\_ltd\_descriptor} must be
freed
individually with this function, even if it was previously allocated as
a part of a contiguous array of descriptors.
\end{itemize}
}
{None.}
{\seef{AllocateLdtDescriptors}}
For an example, see \seef{AllocateLdtDescriptors}.
\functionl{get\_cs}{GetCs}{}{word}{Returns the value of the CS
register.}{None.}{\seef{GetDs},\seef{GetSs}}
\functionl{Get\_Descriptor\_Access\_right}{GetDescriptorAccesRight}{(Des: word)}{Longint}
{\var{Get\_Descriptor\_Access\_right} gets the access rights of a
descriptor \var{Des}.}
{None.}{seef{SetDescriptorAccesRight}}
\functionl{get\_ds}{GetDs}{}{word}{Returns the value of the DS
register.}{None.}{\seef{GetCs},\seef{GetSs}}
\functionl{Get\_Linear\_Addr}{GetLinearAddr}{(PhysAddr : longint;Size : longint)}{longint}
{\var{Get\_Linear\_Addr} converts a physical address \var{PhysAddr} into
a linear address.
@ -595,6 +396,89 @@ a linear address.
For an example, see \seef{AllocateLdtDescriptors}.
\procedurel{get\_meminfo}{GetMeminfo}{(var meminfo : tmeminfo)}{
Returns the current state of memory allocation of the \dos extender.
\textbf{NOTE: }This procedure has nothing to do with the Pascal function
\var{maxavail} and \var{memavail}.}{None.}
{\htmlref{tmeminfo}{ty:tmeminfo}}
\Functionl{Get\_Next\_Selector\_Increment\_Value}
{GetNextSelectorIncrementValue}{word}
{\var{Get\_Next\_Selector\_Increment\_Value} returns the selector increment
value when allocating multiple subsequent descriptors
The function \var{allocate\_ldt\_descriptors} can allocate an array of
contiguous descriptors, but only return the selector for the first. The
value returned by this function can be used to calculate the selectors
for subsequent descriptors in the array.
{\em Notes:}
\begin{itemize}
\item Only works under real DPMI.
\item the increment is always a power of 2.
\end{itemize}
}
{None.}
{\seef{AllocateLdtDescriptors}}
\procedurel{get\_pm\_interrupt}{GetPmInterrupt}{(vector : byte;var intaddr : tseginfo)}
{
Returns the address of the current protected mode handler for the interrupt
\var{vector}.}{None.}
{\seep{SetPmInterrupt},\htmlref{tseginfo}{ty:tseginfo}}
\functionl{get\_run\_mode}{GetRunMode}{}{word}{
This function returns the mode which the extender is currently running.
The function is mostly used to determine if DPMI is supported.
}{None.}
{\htmlref{rm}{co:rmmode}}
Example :
\begin{verbatim}
uses
go32;
begin
if get_run_mode=rm_dpmi then
writeln('DPMI available')
else
writeln('No DPMI available');
end.
\end{verbatim}
\functionl{Get\_Segment\_Base\_Address}{GetSegmentBaseAddress}{(Sel: word)}{Longint}
{
\var{Get\_Segment\_Base\_Address} returns the 32-bit linear base address
from the LDT descriptor for the specified segment (\var{Sel}).
{\em Notes:}
\begin{itemize}
\item Only works under real DPMI.
\end{itemize}
}
{None.}
{\seep{SetSegmentBaseAddress}}
\begin{FPCList}
\item[Example:]
\begin{verbatim}
uses go32;
begin
Writeln(get_segment_base_address(get_ds));
end.
\end{verbatim}
\end{FPCList}
\functionl{get\_ss}{GetSs}{word}{Returns the value of the SS
register.}{None.}{\seef{GetDs},\seef{GetCs}}
\functionl{Global\_Dos\_Alloc}{GlobalDosAlloc}{(Len : longint)}{longint}
{\var{Global\_Dos\_Alloc}
allocates a block of memory with length \var{Len} from the \dos memory pool,
@ -668,12 +552,134 @@ block, described by selector \var{Sel}.
For an example, see \seef{GlobalDosAlloc}.
\function{inportb}{(port : word)}{byte}{Reads a byte from the given I/O
port.}{None.}{\seep{outportb},\seef{inportw},\seef{inportl}}
\function{inportl}{(port : word)}{longint}{Reads a longint from the given I/O
port.}{None.}{\seep{outportl},\seef{inportw},\seef{inportb}}
\function{inportw}{(port : word)}{word}{Reads a word from the given I/O
port.}{None.}{\seep{outportw},\seef{inportb},\seef{inportl}}
\procedure{outportb}{(port : word;data : byte)}{Writes a byte to the
specified port.}{None.}{\seef{inportb},\seep{outportw},\seep{outportl}}
\procedure{outportl}{(port : word;data : longint)}{Writes a longint to the
specified port.}{None.}{\seef{inportl},\seep{outportb},\seep{outportw}}
\procedure{outportw}{(port : word;data : word)}{Writes a word to the
specified port.}{None.}{\seef{inportw},\seep{outportb},\seep{outportl}}
\procedure{realintr}{(intnr : word;var regs : trealregs)}{
\textbf {NOTE: }This procedure works only in DPMI mode.}
{None.}{}
\procedurel{seg\_fillchar}{SegFillChar}{(seg : word;ofs : longint;count : longint;c :
char)}
{Fills a memory area specified by a 48 bit pointer with the given number
of chars.
\textbf {NOTE:} Be careful using this function in non-DPMI mode.
}{None.}{\seep{SegFillWord}, \seep{SegMove}}
\procedurel {seg\_fillword}{SegFillWord}{(seg : word;ofs : longint;count : longint;w :
word)}{Fills a memory area specified by a 48 bit pointer with the given number
of words.
\textbf {NOTE:} Be careful using this function in non-DPMI mode.
}{None.}{\seep{SegFillChar}, \seep{SegMove}}
\functionl{Segment\_To\_Descriptor}{SegmentToDescriptor}{(Seg : Word)}{Word}
{\var{Segment\_To\_Descriptor} Maps a real mode segment (paragraph) address
(in \var{Seg}) onto an descriptor that can be used by a protected mode
program to access the same memory.
The function returns a selector to the DOS real-mode segment.
{\em Notes:}
\begin{itemize}
\item Only works with real DPMI.
\item The descriptors limit will be set to 64KB.
\item multiple calls to this function with the same segment address will
return the same selector.
\item Descriptors created by this function can never be modified or freed.
For this reason this function shouldn't be used too often. Programs
which need to examine various real mode addresses using the same
selector should use the function \var{allocate\_ldt\_descriptors} and change
the base address as necessary.
\end{itemize}
}
{None.}
{}
\begin{FPCList}
\item[Example]
\begin{verbatim}
uses go32;
var r : trealregs;
VGAsel : word;
begin
r.realeax := $13; realintr($10, r);
{ set VGA mode 13h }
VGASel := segment_to_descriptor($A000);
{...}
seg_fillchar(VGAsel, 100*320+6, 1, #15);
{ put a pixel at (6/100) in color 15 }
readln;
{...}
r.realeax := $3; realintr($10, r);
end.
\end{verbatim}
\end{FPCList}
\procedurel{seg\_move}{SegMove}{(sseg : word;source : longint;dseg : word;dest : longint;count :
longint)}
{This procedure copies data when the source and destination are specified
by 48 bit pointers. For example, this function is used by the DPMI version
of \var{dosmemget} and \var{dosmemput}. }{The procedure checks only
for overlapping if source selector equals the destination selector.
Be also careful using this function in non-DPMI
mode.}{\seep{SegFillWord},\seep{SegFillChar}}
\functionl{Set\_Descriptor\_Access\_right}{SetDescriptorAccesRight}{(Des: word; W: word)}{Longint}
{\var{Set\_Descriptor\_Access\_right} sets the access rights of a
descriptor \var{Des}.}
{None.}{seef{GetDescriptorAccesRight}}
\functionl{Get\_Descriptor\_Access\_right}{GetDescriptorAccesRight}{(Des: word)}{Longint}
{\var{Get\_Descriptor\_Access\_right} gets the access rights of a
descriptor \var{Des}.}
{None.}{seef{SetDescriptorAccesRight}}
\procedurel{set\_pm\_interrupt}{SetPmInterrupt}{(vector : byte;const intaddr : tseginfo)}
{Sets a new protected mode handler for the interrupt \var{vector}.}
{None.}{\seep{GetPmInterrupt}, \htmlref{tseginfo}{ty:tseginfo}}
\procedurel{Set\_Segment\_Base\_Address}{SetSegmentBaseAddress}
{(var Des : word;Sel : longint)}
{\var{{Set\_Segment\_Base\_Address}} sets the 32-bit linear base address
of the descriptor \var{Des} for the specified selector \var{Sel}.
{\em Notes:}
\begin{itemize}
\item only works under real DPMI
\end{itemize}
}
{None.}
{ \seef{AllocateLdtDescriptors}, \seep{SetSegmentLimit}}
For an example, see \seef{AllocateLdtDescriptors}.
\procedurel{Set\_Segment\_Limit}{SetSegmentLimit}{(Des : word;Len : longint)}
{\var{Set\_Segment\_Limit} sets the limit of the descriptor \var{Des}
to the specified length \var{Len}
{\em Notes:}
\begin{itemize}
\item Only works under real DPMI.
\item The new limit is the byte length of the segment-1.
\item Segment limits bigger than or equal to 1MB must be page aligned, they
must have the lower 12 bits set.
\end{itemize}
}
{None}
{ \seep{SetSegmentBaseAddress}, \seef{AllocateLdtDescriptors}}
For an example, see \seef{AllocateLdtDescriptors}.

407
docs/sockets.tex
View File

@ -99,129 +99,6 @@ TSockArray = Array[1..2] of Longint;
\section {Functions and Procedures}
\function{Socket}{(Domain,SocketType,Protocol:Longint)}{Longint}
{\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:
\begin{description}
\item[SYS\_EPROTONOSUPPORT]
The protocol type or the specified protocol is not
supported within this domain.
\item[SYS\_EMFILE]
The per-process descriptor table is full.
\item[SYS\_ENFILE]
The system file table is full.
\item[SYS\_EACCESS]
Permission to create a socket of the specified
type and/or protocol is denied.
\item[SYS\_ENOBUFS]
Insufficient buffer space is available. The
socket cannot be created until sufficient
resources are freed.
\end{description}}
{\seef{SocketPair}, \seem{socket}{2}}
for an example, see \seef{Accept}.
\function{Send}{(Sock:Longint;Var Addr;AddrLen,Flags:Longint)}{Longint}
{\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:
\begin{description}
\item[SYS\_EBADF] The socket descriptor is invalid.
\item[SYS\_ENOTSOCK] The descriptor is not a socket.
\item[SYS\_EFAULT] The address is outside your address space.
\item[SYS\_EMSGSIZE] The message cannot be sent atomically.
\item[SYS\_EWOULDBLOCK] The requested operation would block the process.
\item[SYS\_ENOBUFS] The system doesn't have enough free buffers available.
\end{description}
}{\seef{Recv}, \seem{send}{2}}
\function{Recv}{(Sock:Longint;Var Addr;AddrLen,Flags:Longint)}{Longint}
{\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:
\begin{description}
\item[SYS\_EBADF] The socket descriptor is invalid.
\item[SYS\_ENOTCONN] The socket isn't connected.
\item[SYS\_ENOTSOCK] The descriptor is not a socket.
\item[SYS\_EFAULT] The address is outside your address space.
\item[SYS\_EMSGSIZE] The message cannot be sent atomically.
\item[SYS\_EWOULDBLOCK] The requested operation would block the process.
\item[SYS\_ENOBUFS] The system doesn't have enough free buffers available.
\end{description}
}{\seef{Send}}
\function{Bind}{(Sock:Longint;Var Addr;AddrLen:Longint)}{Boolean}
{\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:
\begin{description}
\item[SYS\_EBADF] The socket descriptor is invalid.
\item[SYS\_EINVAL] The socket is already bound to an address,
\item[SYS\_EACCESS] Address is protected and you don't have permission to
open it.
\end{description}
More arrors can be found in the Unix man pages.
}{\seef{Socket}}
\functionl{Bind}{AltBind}{(Sock:longint;const addr:string)}{boolean}
{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{Listen}{(Sock,MaxConnect:Longint)}{Boolean}
{\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:
\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{Accept}{(Sock:Longint;Var Addr;Var Addrlen:Longint)}{Longint}
{\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
@ -261,6 +138,8 @@ The function returns \var{True} if successfull, \var{False} otherwise.
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.
}
@ -268,6 +147,46 @@ The function returns \var{True} if successfull, \var{False} otherwise.
{\seef{Accept}}
\functionl{Accept}{AltCAccept}{(Sock:longint;var addr:TInetSockAddr;var SockIn,SockOut:File)}{Boolean}
{ 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}
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:
\begin{description}
\item[SYS\_EBADF] The socket descriptor is invalid.
\item[SYS\_EINVAL] The socket is already bound to an address,
\item[SYS\_EACCESS] Address is protected and you don't have permission to
open it.
\end{description}
More arrors can be found in the Unix man pages.
}{\seef{Socket}}
\functionl{Bind}{AltBind}{(Sock:longint;const addr:string)}{boolean}
{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
var{Addr}. \var{AddrLen} contains the length of the address.
@ -291,51 +210,28 @@ The function returns \var{True} if successfull, \var{False} otherwise.
{\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.
It is equivalent
to subsequently calling the regular \seef{Connect} function and the
\seep{Sock2File} function.
{ 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}}
\function{Shutdown}{(Sock:Longint;How:Longint)}{Longint}
{\var{ShutDown} closes one end of a full duplex socket connection, described
by \var{Sock}. \var{How} determines how the connection will be shut down,
and can be one of the following:
\begin{description}
\item[0] : Further receives are disallowed.
\item[1] : Further sends are disallowed.
\item[2] : Sending nor receiving are allowed.
\end{description}
\functionl{Connect}{AltCConnect}{(Sock:longint;const addr: TInetSockAddr;var SockIn,SockOut:file)}{Boolean}
{ 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.
On succes, the function returns 0, on error -1 is returned.
}
{\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}}
The function returns \var{True} if successfull, \var{False} otherwise.
}{The errors are those of \seef{Connect}.}
{\seef{Connect}}
\function{GetSocketName}{(Sock:Longint;Var Addr;Var Addrlen:Longint)}{Longint}
{\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:
\begin{description}
\item[SYS\_EBADF] The socket descriptor is invalid.
\item[SYS\_ENOBUFS] The system doesn't have enough buffers to perform the
operation.
\item[SYS\_ENOTSOCK] The descriptor is not a socket.
\item[SYS\_EFAULT] \var{Addr} points outside your address space.
\end{description}
}{\seef{Bind}}
\input{sockex/pfinger.tex}
\function{GetPeerName}{(Sock:Longint;Var Addr;Var Addrlen:Longint)}{Longint}
{\var{GetPeerName} returns the name of the entity connected to the
@ -357,25 +253,22 @@ operation.
\end{description}
}{\seef{Connect}, \seef{Socket}, \seem{connect}{2}}
\function{SetSocketOptions}{(Sock,Level,OptName:Longint;Var OptVal;optlen:longint)}{Longint}
{\var{SetSocketOptions} sets the connection options for socket \var{Sock}.
The socket may be manipulated at different levels, indicated by \var{Level},
which can be one of the following:
\begin{description}
\item[SOL\_SOCKET] To manipulate the socket itself.
\item[XXX] set \var{Level} to \var{XXX}, the protocol number of the protocol
which should interprete the option.
\end{description}
For more information on this call, refer to the unix manual page \seem{setsockopt}{2}.
}
\function{GetSocketName}{(Sock:Longint;Var Addr;Var Addrlen:Longint)}{Longint}
{\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:
\begin{description}
\item[SYS\_EBADF] The socket descriptor is invalid.
\item[SYS\_ENOBUFS] The system doesn't have enough buffers to perform the
operation.
\item[SYS\_ENOTSOCK] The descriptor is not a socket.
\item[SYS\_EFAULT] \var{OptVal} points outside your address space.
\item[SYS\_EFAULT] \var{Addr} points outside your address space.
\end{description}
}
{\seef{GetSocketOptions}}
}{\seef{Bind}}
\function{GetSocketOptions}{(Sock,Level,OptName:Longint;Var OptVal;optlen:longint)}{Longint}
{\var{GetSocketOptions} gets the connection options for socket \var{Sock}.
@ -397,6 +290,158 @@ For more information on this call, refer to the unix manual page \seem{getsockop
}
{\seef{GetSocketOptions}}
\function{Listen}{(Sock,MaxConnect:Longint)}{Boolean}
{\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:
\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
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:
\begin{description}
\item[SYS\_EBADF] The socket descriptor is invalid.
\item[SYS\_ENOTCONN] The socket isn't connected.
\item[SYS\_ENOTSOCK] The descriptor is not a socket.
\item[SYS\_EFAULT] The address is outside your address space.
\item[SYS\_EMSGSIZE] The message cannot be sent atomically.
\item[SYS\_EWOULDBLOCK] The requested operation would block the process.
\item[SYS\_ENOBUFS] The system doesn't have enough free buffers available.
\end{description}
}{\seef{Send}}
\function{Send}{(Sock:Longint;Var Addr;AddrLen,Flags:Longint)}{Longint}
{\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:
\begin{description}
\item[SYS\_EBADF] The socket descriptor is invalid.
\item[SYS\_ENOTSOCK] The descriptor is not a socket.
\item[SYS\_EFAULT] The address is outside your address space.
\item[SYS\_EMSGSIZE] The message cannot be sent atomically.
\item[SYS\_EWOULDBLOCK] The requested operation would block the process.
\item[SYS\_ENOBUFS] The system doesn't have enough free buffers available.
\end{description}
}{\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}.
The socket may be manipulated at different levels, indicated by \var{Level},
which can be one of the following:
\begin{description}
\item[SOL\_SOCKET] To manipulate the socket itself.
\item[XXX] set \var{Level} to \var{XXX}, the protocol number of the protocol
which should interprete the option.
\end{description}
For more information on this call, refer to the unix manual page \seem{setsockopt}{2}.
}
{Errors 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
by \var{Sock}. \var{How} determines how the connection will be shut down,
and can be one of the following:
\begin{description}
\item[0] : Further receives are disallowed.
\item[1] : Further sends are disallowed.
\item[2] : Sending nor receiving are allowed.
\end{description}
On succes, the function returns 0, on error -1 is returned.
}
{\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
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}}
\procedure{Sock2Text}{(Sock:Longint;Var SockIn,SockOut: Text)}
{\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}}
\function{Socket}{(Domain,SocketType,Protocol:Longint)}{Longint}
{\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:
\begin{description}
\item[SYS\_EPROTONOSUPPORT]
The protocol type or the specified protocol is not
supported within this domain.
\item[SYS\_EMFILE]
The per-process descriptor table is full.
\item[SYS\_ENFILE]
The system file table is full.
\item[SYS\_EACCESS]
Permission to create a socket of the specified
type and/or protocol is denied.
\item[SYS\_ENOBUFS]
Insufficient buffer space is available. The
socket cannot be created until sufficient
resources are freed.
\end{description}}
{\seef{SocketPair}, \seem{socket}{2}}
for an example, see \seef{Accept}.
\function{SocketPair}{(Domain,SocketType,Protocol:Longint;var Pair:TSockArray)}{Longint}
{\var{SocketPair} creates 2 sockets in domain \var{Domain}, from type
\var{SocketType} and using protocol \var{Protocol}.
@ -407,20 +452,6 @@ 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{Sock2Text}{(Sock:Longint;Var SockIn,SockOut: Text)}
{\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}}
\procedure{Sock2File}{(Sock:Longint;Var SockIn,SockOut:File)}
{\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}}
\procedure{Str2UnixSockAddr}{(const addr:string;var t:TUnixSockAddr;var len:longint)}
{\var{Str2UnixSockAddr} transforms a Unix socket address in a string to a
\var{TUnixSockAddr} sturcture which can be passed to the \seef{Bind} call.

246
docs/strings.tex
View File

@ -28,72 +28,13 @@ with an explanation.
\section{Functions and procedures.}
\function{StrLen}{(p : PChar)}{Longint}
\procedure{StrAlloc}{(Len : Longint)}{PChar}
{
Returns the length of the null-terminated string \var{P}.
\var{StrAlloc} reserves memory on the heap for a string with length \var{Len},
terminating \var{\#0} included, and returns a pointer to it.
}
{None.}{\seem{Length}{}}
\input{stringex/ex1.tex}
\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}}
\input{stringex/ex2.tex}
\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}}
\input{stringex/ex3.tex}
\function {StrCopy}{(Dest,Source : PChar)}{PChar}
{
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}}
\input{stringex/ex4.tex}
\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}}
\input{stringex/ex5.tex}
\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}}
\input{stringex/ex6.tex}
\function{StrEnd}{(P : PChar)}{PChar}
{
Returns a pointer to the end of \var{P}. (i.e. to the terminating
null-character.
}
{None.}{\seef{StrLen}}
\input{stringex/ex7.tex}
For an example, see \seef{StrPCopy}.
\function{StrCat}{(Dest,Source : PChar)}{PChar}
{
@ -119,6 +60,68 @@ The result is
For an example, see \seef{StrLComp}.
\function {StrCopy}{(Dest,Source : PChar)}{PChar}
{
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}}
\input{stringex/ex4.tex}
\procedure{StrDispose}{(P : PChar)}
{
Removes the string in \var{P} from the heap and releases the memory.
}
{None.}{\seem{Dispose}{}, \seef{StrNew}}
\input{stringex/ex17.tex}
\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}}
\input{stringex/ex6.tex}
\function{StrEnd}{(P : PChar)}{PChar}
{
Returns a pointer to the end of \var{P}. (i.e. to the terminating
null-character.
}
{None.}{\seef{StrLen}}
\input{stringex/ex7.tex}
\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}}
\input{stringex/ex8.tex}
\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}}
\input{stringex/ex12.tex}
\function{StrLComp}{(S1,S2 : PChar; L : Longint)}{Longint}
{
Compares maximum \var{L} characters of the null-terminated strings
@ -135,20 +138,23 @@ The result is
\input{stringex/ex8.tex}
\function{StrIComp}{(S1,S2 : PChar)}{Longint}
\function{StrLCopy}{(Dest,Source : PChar; MaxLen : Longint)}{PChar}
{
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}
Copies \var{MaxLen} characters from \var{Source} to \var{Dest}, and makes
\var{Dest} a null terminated string.
}
{None.}{\seef{StrLComp}, \seef{StrComp}, \seef{StrLIComp}}
{No length checking is performed.}
{\seef{StrCopy}, \seef{StrECopy}}
\input{stringex/ex5.tex}
\input{stringex/ex8.tex}
\function{StrLen}{(p : PChar)}{Longint}
{
Returns the length of the null-terminated string \var{P}.
}
{None.}{\seem{Length}{}}
\input{stringex/ex1.tex}
\function{StrLIComp}{(S1,S2 : PChar; L : Longint)}{Longint}
{
@ -166,6 +172,14 @@ The result is
For an example, see \seef{StrIComp}
\function{StrLower}{(P : PChar)}{PChar}
{
Converts \var{P} to an all-lowercase string. Returns \var{P}.
}
{None.}{\seem{Upcase}{}, \seef{StrUpper}}
\input{stringex/ex14.tex}
\function{StrMove}{(Dest,Source : PChar; MaxLen : Longint)}{PChar}
{
Copies \var{MaxLen} characters from \var{Source} to \var{Dest}. No
@ -176,24 +190,42 @@ Returns \var {Dest}.
\input{stringex/ex10.tex}
\function{StrLCat}{(Dest,Source : PChar; MaxLen : Longint)}{PChar}
\function{StrNew}{(P : PChar)}{PChar}
{
Adds \var{MaxLen} characters from \var{Source} to \var{Dest}, and adds a
terminating null-character. Returns \var{Dest}.
Copies \var{P} to the Heap, and returns a pointer to the copy.
}
{None.}{\seef{StrCat}}
{Returns \var{Nil} if no memory was available for the copy.}
{\seem{New}{}, \seef{StrCopy}, \seep{StrDispose}}
\input{stringex/ex12.tex}
\input{stringex/ex16.tex}
\function{StrScan}{(P : PChar; C : Char)}{PChar}
\function {StrPas}{(P : PChar)}{String}
{
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}.
Converts a null terminated string in \var{P} to a Pascal string, and returns
this string. The string is truncated at 255 characters.
}
{None.}{\seem{Pos}{}, \seef{StrRScan}, \seef{StrPos}}
{None.}{ \seef{StrPCopy}}
\input{stringex/ex13.tex}
\input{stringex/ex3.tex}
\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}}
\input{stringex/ex2.tex}
\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}}
\input{stringex/ex15.tex}
\function{StrRScan}{(P : PChar; C : Char)}{PChar}
{
@ -205,13 +237,15 @@ null-terminated string \var{P}. If \var{C} does not occur, returns
For an example, see \seef{StrScan}.
\function{StrLower}{(P : PChar)}{PChar}
\function{StrScan}{(P : PChar; C : Char)}{PChar}
{
Converts \var{P} to an all-lowercase string. Returns \var{P}.
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{Upcase}{}, \seef{StrUpper}}
{None.}{\seem{Pos}{}, \seef{StrRScan}, \seef{StrPos}}
\input{stringex/ex14.tex}
\input{stringex/ex13.tex}
\function{StrUpper}{(P : PChar)}{PChar}
{
@ -220,37 +254,3 @@ Converts \var{P} to an all-uppercase string. Returns \var{P}.
{None.}{\seem{Upcase}{}, \seef{StrLower}}
For an example, see \seef{StrLower}
\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}}
\input{stringex/ex15.tex}
\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}}
\input{stringex/ex16.tex}
\procedure{StrDispose}{(P : PChar)}
{
Removes the string in \var{P} from the heap and releases the memory.
}
{None.}{\seem{Dispose}{}, \seef{StrNew}}
\input{stringex/ex17.tex}
\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}.