fpc/docs/dos.tex

%
%   $Id$
%   This file is part of the FPC documentation.
%   Copyright (C) 1997, by Michael Van Canneyt
%
%   The FPC documentation is free text; you can redistribute it and/or
%   modify it under the terms of the GNU Library General Public License as
%   published by the Free Software Foundation; either version 2 of the
%   License, or (at your option) any later version.
%
%   The FPC Documentation is distributed in the hope that it will be useful,
%   but WITHOUT ANY WARRANTY; without even the implied warranty of
%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
%   Library General Public License for more details.
%
%   You should have received a copy of the GNU Library General Public
%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
%   Boston, MA 02111-1307, USA. 
%
\chapter{The DOS unit.}
\FPCexampledir{dosex}

This chapter describes the \var{DOS} unit for Free pascal, both under
\dos, \ostwo, \windows and \linux. 
The unit was first written for \dos by Florian kl\"ampfl. It was ported to 
\linux by Mark May\footnote{Current e-mail address \textsf{[email protected]}}, 
and enhanced by Micha\"el Van Canneyt. The \amiga version was ported by
Nils Sjoholm.

Under non-\dos systems, some of the functionality is lost, as it is either impossible 
or meaningless to implement it. Other than that, the functionality for all 
operating systems is the same.

This chapter is divided in three sections:
\begin{itemize}
\item The first section lists the pre-defined constants, types and variables. 
\item The second section gives an overview of all functions available,
grouped by category.
\item The third section describes the functions which appear in the
interface part of the DOS unit.
\end{itemize}

\section{Types, Variables, Constants}
\subsection {Constants}
The DOS unit implements the following constants:
\begin{verbatim}
  {Bitmasks for CPU Flags}
  fcarry =     $0001;
  fparity =    $0004;
  fauxiliary = $0010;
  fzero =      $0040;
  fsign =      $0080;
  foverflow  = $0800;
  {Bitmasks for file attribute}
  readonly =   $01;
  hidden =     $02;
  sysfile =    $04;
  volumeid =   $08;
  directory =  $10;
  archive =    $20;
  anyfile =    $3F;
  fmclosed =   $D7B0;
  fminput =    $D7B1;
  fmoutput =   $D7B2;
  fminout =    $D7B3;
\end{verbatim}
\subsection{Types}
The following string types are defined for easy handling of
filenames :
\begin{verbatim}
  ComStr  = String[255];   { For command-lines } 
  PathStr = String[255];   { For full path for file names }
  DirStr  = String[255];   { For Directory and (DOS) drive string }
  NameStr = String[255];   { For Name of file }
  ExtStr  = String[255];   { For Extension of file }
\end{verbatim}
\begin{verbatim}
  SearchRec = Packed Record
    Fill : array[1..21] of byte;  
    { Fill replaced with declarations below, for Linux}
    Attr : Byte; {attribute of found file}
    Time : LongInt; {last modify date of found file}
    Size : LongInt; {file size of found file}
    Reserved : Word; {future use}
    Name : String[255]; {name of found file}
    SearchSpec: String[255]; {search pattern}
    NamePos: Word; {end of path, start of name position}
    End;
\end{verbatim}
Under \linux, the \var{Fill} array is replaced with the following:
\begin{verbatim}
    SearchNum: LongInt; {to track which search this is}
    SearchPos: LongInt; {directory position}
    DirPtr: LongInt; {directory pointer for reading directory}
    SearchType: Byte;  {0=normal, 1=open will close}
    SearchAttr: Byte; {attribute we are searching for}
    Fill: Array[1..07] of Byte; {future use}
\end{verbatim}
This is because the searching meachanism on Unix systems is substantially
different from \dos's, and the calls have to be mimicked.
\begin{verbatim}
const
  filerecnamelength = 255;
type
  FileRec = Packed Record
    Handle,
    Mode,  
    RecSize   : longint;
    _private  : array[1..32] of byte;
    UserData  : array[1..16] of byte;
    name      : array[0..filerecnamelength] of char;
  End;
\end{verbatim}
\var{FileRec} is used for internal representation of typed and untyped files.
Text files are handled by the following types :
\begin{verbatim}
const
  TextRecNameLength = 256;
  TextRecBufSize    = 256;
type
  TextBuf = array[0..TextRecBufSize-1] of char;
  TextRec = Packed Record
    Handle,
    Mode,  
    bufsize,
    _private,
    bufpos,  
    bufend    : longint;
    bufptr    : ^textbuf;
    openfunc,
    inoutfunc,
    flushfunc,
    closefunc : pointer;
    UserData  : array[1..16] of byte;
    name      : array[0..textrecnamelength-1] of char;
    buffer    : textbuf;
  End;
\end{verbatim}
Remark that this is not binary compatible with the Turbo Pascal definition
of \var{TextRec}, since the sizes of the different fields are different.
\begin{verbatim}
    Registers = record
      case i : integer of
        0 : (ax,f1,bx,f2,cx,f3,dx,f4,bp,f5,si,
             f51,di,f6,ds,f7,es,f8,flags,fs,gs : word);
        1 : (al,ah,f9,f10,bl,bh,f11,f12,
             cl,ch,f13,f14,dl,dh : byte);
        2 : (eax,  ebx,  ecx,  edx,  ebp,  esi,  edi : longint);
        End;
\end{verbatim}
The  \var{registers} type is used in the \var{MSDos} call.
\begin{verbatim}
  DateTime = record
    Year: Word;
    Month: Word;
    Day: Word;
    Hour: Word;
    Min: Word;
    Sec: word;
    End;
\end{verbatim}
The \var{DateTime} type is used in \seep{PackTime} and \seep{UnPackTime} for
setting/reading file times with \seep{GetFTime} and \seep{SetFTime}.
\subsection{Variables}
\begin{verbatim}
    DosError : integer;
\end{verbatim}
The \var{DosError} variable is used by the procedures in the \dos unit to 
report errors. It can have the following values :
\begin{center}
\begin{tabular}{cl}
2 & File not found. \\
3 & path not found. \\
5 & Access denied. \\
6 & Invalid handle. \\
8 & Not enough memory. \\
10 & Invalid environment. \\
11 & Invalid format. \\
18 & No more files.
\end{tabular}
\end{center}
Other values are possible, but are not documented.
%\begin{verbatim}
%    drivestr : array [0..26] of pchar;
%\end{verbatim}
%This variable is defined in the \linux version of the \dos unit. It is used
%in the \seef{DiskFree} and \seef{DiskSize} calls.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Functions and procedures by category
\section{Function list by category}
What follows is a listing of the available functions, grouped by category.
For each function there is a reference to the page where you can find the
function.

\subsection{File handling}
Routines to handle files on disk.
\begin{funclist}
\funcrefl{FExpand}{Dos:FExpand}{Expand filename to full path}
\procref{FindClose}{Close finfirst/findnext session}
\procref{FindFirst}{Start find of file}
\procref{FindNext}{Find next file}
\funcrefl{FSearch}{Dos:FSearch}{Search for file in a path}
\procref{FSplit}{Split filename in parts}
\procref{GetFAttr}{Return file attributes}
\procref{GetFTime}{Return file time}
\funcref{GetLongName}{Convert short filename to long filename}
\funcref{GetShortName}{Convert long filename to short filename}
\procref{SetFAttr}{Set file attributes}
\procref{SetFTime}{Set file time}
\end{funclist}

\subsection{Directory and disk handling}
Routines to handle disk information.
\begin{funclist}
\procref{AddDisk}{Add disk to list of disks}
\funcref{DiskFree}{Return size of free disk space}
\funcref{DiskSize}{Return total disk size}
\end{funclist}

\subsection{Process handling}
Functions to handle process information and starting new processes.
\begin{funclist}
\funcref{DosExitCode}{Exit code of last executed program}
\funcref{EnvCount}{Return number of environment variables}
\funcref{EnvStr}{Return environment string pair}
\procref{Exec}{Execute program}
\funcrefl{GetEnv}{Dos:GetEnv}{Return specified environment string}
\end{funclist}

\subsection{System information}
Functions for retrieving and setting general system information such as date
and time.
\begin{funclist}
\funcref{DosVersion}{Get OS version}
\procref{GetCBreak}{Get setting of control-break handling flag}
\procrefl{GetDate}{Dos:GetDate}{Get system date}
\procref{GetIntVec}{Get interrupt vector status}
\procrefl{GetTime}{Dos:GetTime}{Get system time}
\procref{GetVerify}{Get verify flag}
\procref{Intr}{Execute an interrupt}
\procref{Keep}{Keep process in memory and exit}
\procref{MSDos}{Execute MS-dos function call}
\procref{PackTime}{Pack time for file time}
\procref{SetCBreak}{Set control-break handling flag}
\procref{SetDate}{Set system date}
\procref{SetIntVec}{Set interrupt vectors}
\procref{SetTime}{Set system time}
\procref{SetVerify}{Set verify flag}
\procref{SwapVectors}{Swap interrupt vectors}
\procref{UnPackTime}{Unpack file time}
\end{funclist}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Functions and procedures
\section{Functions and Procedures}
\begin{procedure}{AddDisk}
\Declaration
Procedure AddDisk (Const S : String);
\Description
\var{AddDisk} adds a filename \var{S} to the internal list of disks. It is
implemented for \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}
\item \var{'.'} for the current drive, 
\item \var{'/fd0/.'} for the first floppy-drive.
\item \var{'/fd1/.'} for the second floppy-drive.
\item \var{'/'} for the first hard disk.
\end{itemize}
The first call to \var{AddDisk} will therefore add a name for the second
harddisk, The second call for the third drive, and so on until 23 drives
have been added (corresponding to drives \var{'D:'} to \var{'Z:'})
\Errors
None
\SeeAlso
\seef{DiskFree}, \seef{DiskSize} 
\end{procedure}


\begin{function}{DiskFree}
\Declaration
Function DiskFree (Drive: byte) : Int64;
\Description

\var{DiskFree} returns the number of free bytes on a disk. The parameter
\var{Drive} indicates which disk should be checked. This parameter is 1 for
floppy \var{a:}, 2 for floppy \var{b:}, etc. A value of 0 returns the free
space on the current drive. 
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}
\item \var{'.'} for the current drive, 
\item \var{'/fd0/.'} for the first floppy-drive.
\item \var{'/fd1/.'} for the second floppy-drive.
\item \var{'/'} for the first hard disk.
\end{itemize}
There is room for 1-26 drives. You can add a drive with the
\seep{AddDisk} procedure.
These settings can be coded in \var{dos.pp}, in the initialization part.

\Errors
-1 when a failure occurs, or an invalid \var{drivenr} is given.
\SeeAlso
\seef{DiskSize}, \seep{AddDisk}
\end{function}

\FPCexample{ex6}

\begin{function}{DiskSize}
\Declaration
Function DiskSize (Drive: byte) : Int64;
\Description

\var{DiskSize} returns the total size (in bytes) of a disk. The parameter
\var{Drive} indicates which disk should be checked. This parameter is 1 for
floppy \var{a:}, 2 for floppy \var{b:}, etc. A value of 0 returns the size
of the current drive. 
\textbf{For \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}
\item \var{'.'} for the current drive, 
\item \var{'/fd0/.'} for the first floppy-drive.
\item \var{'/fd1/.'} for the second floppy-drive.
\item \var{'/'} for the first hard disk.
\end{itemize}
There is room for 1-26 drives. You can add a drive with the
\seep{AddDisk} procedure.
These settings can be coded in \var{dos.pp}, in the initialization part.

\Errors
-1 when a failure occurs, or an invalid drive number is given.
\SeeAlso
\seef{DiskFree}, \seep{AddDisk}
\end{function}
For an example, see \seef{DiskFree}.
\begin{function}{DosExitCode}
\Declaration
Function DosExitCode  : Word;
\Description

\var{DosExitCode} contains (in the low byte) the exit-code of a program 
executed with the \var{Exec} call.
\Errors
None.
\SeeAlso
\seep{Exec}
\end{function}

\FPCexample{ex5}

\begin{function}{DosVersion}
\Declaration
Function DosVersion  : Word;
\Description
\var{DosVersion} returns the \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)
\Errors
None.
\SeeAlso

\end{function}


\FPCexample{ex1}


\begin{function}{EnvCount}
\Declaration
Function EnvCount  : longint;\Description
\var{EnvCount} returns the number of environment variables.
\Errors
None.
\SeeAlso
\seef{EnvStr}, \seef{Dos:GetEnv}
\end{function}

\begin{function}{EnvStr}
\Declaration
Function EnvStr (Index: integer) : string;\Description

\var{EnvStr} returns the \var{Index}-th \var{Name=Value} pair from the list
of environment variables. 
The index of the first pair is zero.
\Errors
The length is limited to 255 characters. This may cause problems under
\linux. The \linux unit solves this problem.
\SeeAlso
\seef{EnvCount}, \seef{Dos:GetEnv}
\end{function}

\FPCexample{ex13}

\begin{procedure}{Exec}
\Declaration
Procedure Exec (const Path: pathstr; const ComLine: comstr);
\Description

\var{Exec} executes the program in \var{Path}, with the options given by
\var{ComLine}.
After the program has terminated, the procedure returns. The Exit value of
the program can be consulted with the \var{DosExitCode} function.

\Errors
Errors are reported in \var{DosError}.
\SeeAlso
\seef{DosExitCode}
\end{procedure}
For an example, see \seef{DosExitCode}
\begin{functionl}{FExpand}{Dos:FExpand}
\Declaration
Function FExpand (const path: pathstr) : pathstr;
\Description

\var{FExpand} takes its argument and expands it to a complete filename, i.e.
a filename starting from the root directory of the current drive, prepended
with the drive-letter (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)

\Errors
\seep{FSplit}
\SeeAlso
\lstinputlisting{dosex/ex5.pp}
\end{functionl}

\begin{procedure}{FindClose}
\Declaration
Procedure FindClose (Var F: SearchRec);
\Description
\textbf{\linux, \windows and \ostwo wonly}
\var{FindClose} frees any resources associated with the search record
\var{F}.

Under \linux, \windows and \ostwo the \var{findfirst/findnext} calls have 
to be mimicked. This call is needed to free any internal resources allocated
by the \seef{FindFirst} or \seef{FindNext} calls.

E.g. on \linux, 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 
on \linux.

\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.

On \ostwo, you cannot issue two different \var{FindFirst} calls. That is,
you must close any previous search operation with \seep{FindClose} before
starting a new one. Failure to do so will end in a Run-Time Error 6 
(Invalid file handle)

Also, on \ostwo, the boolean variable \var{FileNameCaseSensitive} indicates
whether searches are conducted case-sensitive or not. By default, searches
are not case sensitive. If the varieble is set to \var{True}, searches on
\ostwo are case sensistive.
\Errors
Errors are reported in DosError.
\SeeAlso
\seep{FindNext},
\seep{FindClose}
\end{procedure}

\FPCexample{ex7}

\begin{procedure}{FindNext}
\Declaration
Procedure FindNext (var f: searchRec);
\Description

\var{FindNext} takes as an argument a \var{SearchRec} from a previous
\var{FindNext} call, or a \var{FindFirst} call, and tries to find another
file which matches the criteria, specified in the \var{FindFirst} call.
If \var{DosError} is different from zero, no more files matching the
criteria were found.
\Errors
\var{DosError} is used to report errors.
\SeeAlso
\seep{FindFirst}, \seep{FindClose}
\end{procedure}
For an example, see \seep{FindFirst}.
\begin{functionl}{FSearch}{Dos:FSearch}
\Declaration
Function FSearch (Path: pathstr; DirList: string) : pathstr;
\Description
\var{FSearch} searches the file \var{Path} in all directories listed in
\var{DirList}. The full name of the found file is returned.
\var{DirList} must be a list of directories, separated by semi-colons (or
colons under \linux).
When no file is found, an empty string is returned.

\Errors
None.
\SeeAlso
\seefl{FExpand}{Dos:FExpand}
\end{functionl}

\FPCexample{ex10}

 
\begin{procedure}{FSplit}
\Declaration
Procedure FSplit (path: pathstr; \\ var dir: dirstr; var name: namestr;
  var ext: extstr);
\Description

\var{FSplit} splits a full file name into 3 parts : A \var{Path}, a
\var{Name} and an extension  (in \var{ext}.) 
The extension is taken to be all letters after the {\em last} dot (.). For 
\dos, however, an exception is made when \var{LFNSupport=False}, then
the extension is defined as all characters after the {\em first} dot.

\Errors
None.
\SeeAlso
\seefl{FSearch}{Dos:FSearch}
\end{procedure}

\FPCexample{ex12}

\begin{procedure}{GetCBreak}
\Declaration
Procedure GetCBreak (var breakvalue: boolean);
\Description

\var{GetCBreak} gets the status of CTRL-Break checking under \dos.
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.
\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

\var{GetDate} returns the system's date. \var{Year} is a number in the range
1980..2099.\var{mday} is the day of the month,
\var{wday} is the day of the week, starting with Sunday as day 0.
\Errors
None.
\SeeAlso
\seepl{GetTime}{Dos:GetTime},\seep{SetDate}
\end{procedurel}

\FPCexample{ex2}

\begin{functionl}{GetEnv}{Dos:GetEnv}
\Declaration
Function GetEnv (EnvVar: String) : String;
\Description

\var{Getenv} returns the value of the environment variable \var{EnvVar}.
Under \linux, case is important when looking for \var{EnvVar}.
When there is no environment variable \var{EnvVar} defined, an empty
string is returned.
\Errors
None.
\SeeAlso
\seef{EnvCount}, \seef{EnvStr}
\end{functionl}

\FPCexample{ex14}

\begin{procedure}{GetFAttr}
\Declaration
Procedure GetFAttr (var F; var Attr: word);
\Description

\var{GetFAttr} returns the file attributes of the file-variable \var{f}.
 \var{F} can be a untyped or typed file, or of type \var{Text}. \var{f} must
have been assigned, but not opened. The attributes can be examined with the
following constants :
\begin{itemize}
\item \var{ReadOnly  = 01h}
\item \var{Hidden    = 02h}
\item \var{SysFile   = 04h}
\item \var{VolumeId  = 08h}
\item \var{Directory = 10h}
\item \var{Archive   = 20h}
\end{itemize}
Under \linux, supported attributes are:
\begin{itemize}
\item \var{Directory}
\item \var{ReadOnly} if the current process doesn't have access to the file.
\item \var{Hidden} for files whose name starts with a dot \var{('.')}.
\end{itemize}

\Errors
Errors are reported in \var{DosError}
\SeeAlso
\seep{SetFAttr}
\end{procedure}

\FPCexample{ex8}

\begin{procedure}{GetFTime}
\Declaration
Procedure GetFTime (var F; var Time: longint);
\Description

\var{GetFTime} returns the modification time of a file.
This time is encoded and must be decoded with \var{UnPackTime}. 
\var{F} must be a file type, which has been assigned, and
opened.
\Errors
Errors are reported in \var{DosError}
\SeeAlso
\seep{SetFTime}, \seep{PackTime},\seep{UnPackTime}
\end{procedure}

\FPCexample{ex9}

\begin{procedure}{GetIntVec}
\Declaration
Procedure GetIntVec (IntNo: byte; var Vector: pointer);
\Description

\var{GetIntVec} returns the address of interrupt vector
\var{IntNo}.
\Errors
Under non- \dos operating systems, this call does nothing.
\SeeAlso
\seep{SetIntVec}
\end{procedure}

\begin{function}{GetLongName}
\Declaration
function GetLongName(var p : String) : boolean;\Description
This function is only implemented in the GO32V2 version of \fpc.

\var{GetLongName} changes the filename \var{p} to a long filename
if the \dos call to do this is successful. The resulting string
is the long  file name corresponding to the short filename \var{p}.

The function returns \var{True} if the \dos call was successful, 
\var{False} otherwise.

This function should only be necessary when using the DOS extender
under Windows 95 and higher.
\Errors
If the \dos call was not succesfull, \var{False} is returned.
\SeeAlso
\seef{GetShortName}
\end{function}

\begin{function}{GetShortName}
\Declaration
function GetShortName(var p : String) : boolean;\Description
This function is only implemented in the GO32V2 version of \fpc.

\var{GetShortName} changes the filename \var{p} to a short filename
if the \dos call to do this is successful. The resulting string
is the short file name corresponding to the long filename \var{p}.

The function returns \var{True} if the \dos call was successful, 
\var{False} otherwise.

This function should only be necessary when using the DOS extender
under Windows 95 and higher.
\Errors
If the \dos call was not successful, \var{False} is returned.
\SeeAlso
\seef{GetLongName}
\end{function}

\begin{procedurel}{GetTime}{Dos:GetTime}
\Declaration
Procedure GetTime (var hour, minute, second, sec100: word);
\Description

\var{GetTime} returns the system's time. \var{Hour} is a on a 24-hour time
scale. \var{sec100} is in hundredth of a
second.
\Errors
None.
\SeeAlso
\seepl{GetDate}{Dos:GetDate},
\seep{SetTime}
\end{procedurel}


\FPCexample{ex3}


\begin{procedure}{GetVerify}
\Declaration
Procedure GetVerify (var verify: boolean);
\Description

\var{GetVerify} returns the status of the verify flag under \dos. When
\var{Verify} is \var{True}, then \dos checks data which are written to disk,
by reading them after writing. If \var{Verify} is \var{False}, then data
written to disk are not verified.
\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

\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}.
\Errors
Under \linux this call does nothing, because interrupts are managed by the
kernel. The only allowed interrupt is 80h, the Linux kernel entry interrupt.
\SeeAlso
\seep{MSDos}, see the \linux unit.
\end{procedure}

\begin{procedure}{Keep}
\Declaration
Procedure Keep (ExitCode: word);
\Description
\var{Keep} terminates the program, but stays in memory. This is used for TSR
(Terminate Stay Resident) programs which catch some interrupt.
\var{ExitCode} is the same parameter as the \var{Halt} function takes.
\Errors
Under non-\dos operating systems, this call does nothing.
\SeeAlso
\seem{Halt}{}
\end{procedure}
\begin{procedure}{MSDos}
\Declaration
Procedure MSDos (var regs: registers);
\Description

\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.
\Errors
None.
\SeeAlso
\seep{Intr}
\end{procedure}
\begin{procedure}{PackTime}
\Declaration
Procedure PackTime (var T: datetime; var P: longint);
\Description

\var{UnPackTime} converts the date and time specified in \var{T}
to a packed-time format which can be fed to \var{SetFTime}.
\Errors
None.
\SeeAlso
\seep{SetFTime}, \seep{FindFirst}, \seep{FindNext}, \seep{UnPackTime}
\end{procedure}

\FPCexample{ex4}

\begin{procedure}{SetCBreak}
\Declaration
Procedure SetCBreak (breakvalue: boolean);
\Description

\var{SetCBreak} sets the status of CTRL-Break checking 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.
\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

\var{SetDate} sets the system's internal date. \var{Year} is a number
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.
\SeeAlso
\seep{Dos:GetDate},
\seep{SetTime}
\end{procedure}

\begin{procedure}{SetFAttr}
\Declaration
Procedure SetFAttr (var F; Attr: word);
\Description

\var{SetFAttr} sets the file attributes of the file-variable \var{F}.
 \var{F} can be a untyped or typed file, or of type \var{Text}. \var{F} must
have been assigned, but not opened. The attributes can be a sum of the
following constants:
\begin{itemize}
\item \var{ReadOnly  = 01h}
\item \var{Hidden    = 02h}
\item \var{SysFile   = 04h}
\item \var{VolumeId  = 08h}
\item \var{Directory = 10h}
\item \var{Archive   = 20h}
\item \var{AnyFile   = 3fh}
\end{itemize}

\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

\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
Errors are reported in \var{DosError}
\SeeAlso
\seep{GetFTime}, \seep{PackTime},\seep{UnPackTime}
\end{procedure}

\begin{procedure}{SetIntVec}
\Declaration
Procedure SetIntVec (IntNo: byte; Vector: pointer);
\Description
\var{SetIntVec} sets interrupt vector \var{IntNo} to \var{Vector}.
\var{Vector} should point to an interrupt procedure.
\Errors
Under non- \dos operating systems, this call does nothing.
\SeeAlso
\seep{GetIntVec}
\end{procedure}

\begin{procedure}{SetTime}
\Declaration
Procedure SetTime (hour,minute,second,sec100: word);
\Description
\var{SetTime} sets the system's internal clock. The \var{Hour} parameter is
on a 24-hour time scale.
\Errors
this call exists, but is not implemented on \linux, 
as setting the time is a root-only privilege.
\SeeAlso
\seep{Dos:GetTime}, \seep{SetDate}
\end{procedure}
\begin{procedure}{SetVerify}
\Declaration
Procedure SetVerify (verify: boolean);
\Description

\var{SetVerify} sets the status of the verify flag under \dos. When
\var{Verify} is \var{True}, then \dos checks data which are written to disk,
by reading them after writing. If \var{Verify} is \var{False}, then data
written to disk are not verified.
\Errors
Under \linux,  Verify is always
\var{True}.
\SeeAlso
\seep{SetVerify}
\end{procedure}
\begin{procedure}{SwapVectors}
\Declaration
Procedure SwapVectors ;
\Description

\var{SwapVectors} swaps the contents of the internal table of interrupt 
vectors with the current contents of the interrupt vectors.
This is called typically in before and after an \var{Exec} call.

\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

\var{UnPackTime} converts the file-modification time in \var{p}
to a \var{DateTime} record. The file-modification time can be 
returned by \var{GetFTime}, \var{FindFirst} or \var{FindNext} calls.
\Errors
None.
\SeeAlso
\seep{GetFTime}, \seep{FindFirst}, \seep{FindNext}, \seep{PackTime}
\end{procedure}
For an example, see \seep{PackTime}.