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. The \var{DOS}
unit gives access to some operating system calls related to files, the
file system, date and time. Except for the \palmos target, this unit is
available to all supported platforms.

The unit was first written for \dos by Florian Kl\"ampfl. It was ported to 
\linux by Mark May\footnote{Current e-mail address \textsf{mmay@dnaco.net}}, 
and enhanced by Micha\"el Van Canneyt. The \amiga version was ported by
Nils Sjoholm.

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

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

\section{Types, Variables, Constants}


\subsection {Constants}
The DOS unit implements the following constants:

\subsubsection{File attributes}

The File Attribute constants are used in \seep{FindFirst}, \seep{FindNext} to
determine what type of special file to search for in addition to normal files. 
These flags are also used in the \seep{SetFAttr} and \seep{GetFAttr} routines to 
set and retrieve attributes of files. For their definitions consult 
\seet{fileattributes}.

\begin{FPCltable}{lll}{Possible file attributes}{fileattributes}
\hline
Constant & Description & Value\\ \hline
\var{readonly} & Read only file & \$01\\
\var{hidden} & Hidden file & \$02 \\
\var{sysfile} & System file & \$04\\
\var{volumeid} & Volume label & \$08\\
\var{directory} & Directory & \$10\\
\var{archive} & Archive & \$20\\ 
\var{anyfile} & Any of the above special files & \$3F\\
\hline
\end{FPCltable}

\subsubsection{fmXXXX}

These constants are used in the \var{Mode} field of the \var{TextRec}
record. Gives information on the filemode of the text I/O. For their
definitions consult \seet{fmxxxconstants}.

\begin{FPCltable}{lll}{Possible mode constants}{fmxxxconstants}
\hline
Constant & Description & Value\\ \hline
\var{fmclosed} & File is closed & \$D7B0\\
\var{fminput} & File is read only & \$D7B1 \\
\var{fmoutput} & File is write only & \$D7B2\\
\var{fminout} & File is read and write & \$D7B3\\
\hline
\end{FPCltable}

\subsubsection{Other}

The following constants are not portable, and should not be used. They
are present for compatibility only.

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

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

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

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

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

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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Functions and procedures
\section{Functions and Procedures}
\begin{procedure}{AddDisk}
\Declaration
Procedure AddDisk (Const S : String);
\Description
\var{AddDisk} adds a filename \var{S} to the internal list of disks. It is
implemented for systems which do not use DOS type drive letters.
 This list is used to determine which disks to use in the \seef{DiskFree}
and \seef{DiskSize} calls. 
The \seef{DiskFree} and \seef{DiskSize} functions need a file on the 
specified drive, since this is required for the \var{statfs} system call.
The names are added sequentially. The dos
initialization code presets the first three disks to:
\begin{itemize}
\item \var{'.'} for the current drive, 
\item \var{'/fd0/.'} for the first floppy-drive (linux only).
\item \var{'/fd1/.'} for the second floppy-drive (linux only).
\item \var{'/'} for the first hard disk.
\end{itemize}
The first call to \var{AddDisk} will therefore add a name for the second
harddisk, The second call for the third drive, and so on until 23 drives
have been added (corresponding to drives \var{'D:'} to \var{'Z:'})
\Errors
None
\SeeAlso
\seef{DiskFree}, \seef{DiskSize} 
\end{procedure}


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

\var{DiskFree} returns the number of free bytes on a disk. The parameter
\var{Drive} indicates which disk should be checked. This parameter is 1 for
floppy \var{a:}, 2 for floppy \var{b:}, etc. A value of 0 returns the free
space on the current drive. 

\textbf{For \unix only:}\\
The \var{diskfree} and \var{disksize} functions need a file on the 
specified drive, since this is required for the \var{statfs} system call.
These filenames are set in the initialization of the dos unit, and have 
been preset to :
\begin{itemize}
\item \var{'.'} for the current drive, 
\item \var{'/fd0/.'} for the first floppy-drive (linux only).
\item \var{'/fd1/.'} for the second floppy-drive (linux only).
\item \var{'/'} for the first hard disk.
\end{itemize}
There is room for 1-26 drives. You can add a drive with the
\seep{AddDisk} procedure.
These settings can be coded in \var{dos.pp}, in the initialization part.

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

\FPCexample{ex6}

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

\var{DiskSize} returns the total size (in bytes) of a disk. The parameter
\var{Drive} indicates which disk should be checked. This parameter is 1 for
floppy \var{a:}, 2 for floppy \var{b:}, etc. A value of 0 returns the size
of the current drive. 

\textbf{For \unix only:}\\
The \var{diskfree} and \var{disksize} functions need a file on the specified drive, since this
is required for the \var{statfs} system call.
  These filenames are set in the initialization of the dos unit, and have 
been preset to :
\begin{itemize}
\item \var{'.'} for the current drive, 
\item \var{'/fd0/.'} for the first floppy-drive (linux only).
\item \var{'/fd1/.'} for the second floppy-drive (linux only).
\item \var{'/'} for the first hard disk.
\end{itemize}
There is room for 1-26 drives. You can add a drive with the
\seep{AddDisk} procedure.
These settings can be coded in \var{dos.pp}, in the initialization part.

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

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

\FPCexample{ex5}

\begin{function}{DosVersion}
\Declaration
Function DosVersion  : Word;
\Description
\var{DosVersion} returns the operating system or kernel version. The
low byte contains the major version number, while the high byte 
contains the minor version number.
\Portability
On systems where versions consists of more then two numbers, 
only the first two numbers will be returned. For example Linux version 2.1.76 
will give you DosVersion 2.1. Some operating systems, such as \freebsd, do not
have system calls to return the kernel version, in that case a value of 0 will
be returned.
\Errors
None.
\SeeAlso

\end{function}


\FPCexample{ex1}


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

\begin{function}{EnvStr}
\Declaration
Function EnvStr (Index: 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. 
\SeeAlso
\seef{EnvCount}, \seef{Dos:GetEnv}
\end{function}

\FPCexample{ex13}

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

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

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

\var{FExpand} takes its argument and expands it to a complete filename, i.e.
a filename starting from the root directory of the current drive, prepended
with the drive-letter or volume name (when supported).
\Portability
On case sensitive file systems (such as \unix and \linux), the resulting
name is left as it is, otherwise it is converted to uppercase.
\Errors
\seep{FSplit}
\SeeAlso
\end{functionl}

\FPCexample{ex5}

\begin{procedure}{FindClose}
\Declaration
Procedure FindClose (Var F: SearchRec);
\Description
\var{FindClose} frees any resources associated with the search record
\var{F}.

This call is needed to free any internal resources allocated by the 
\seef{FindFirst} or \seef{FindNext} calls.


The \linux implementation of the \dos unit therefore keeps a table of open
directories, and when the table is full, closes one of the directories, and
reopens another. This system is adequate but slow if you use a lot of
\var{searchrecs}.
So, to speed up the findfirst/findnext system, the \var{FindClose} call was
implemented. When you don't need a \var{searchrec} any more, you can tell
this to the \dos unit by issuing a \var{FindClose} call. The directory
which is kept open for this \var{searchrec} is then closed, and the table slot
freed.

\Portability
It is recommended to use the \linux call \var{Glob} when looking for files 
on \linux.

\Errors
Errors are reported in DosError.
\SeeAlso
\seef{Glob}.
\end{procedure}

\begin{procedure}{FindFirst}
\Declaration
Procedure FindFirst (const Path: pathstr; Attr: word; var F: SearchRec);
\Description

\var{FindFirst} searches the file specified in \var{Path}. Normal files,
as well as all special files which have the attributes specified in
\var{Attr} will be returned.

It returns a \var{SearchRec} record for further searching in \var{F}.
\var{Path} can contain the wildcard characters \var{?} (matches any single
character) and \var{*} (matches 0 ore more arbitrary characters). In this
case \var{FindFirst} will return the first file which matches the specified
criteria.
If \var{DosError} is different from zero, no file(s) matching the criteria 
was(were) found.

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

\Errors
Errors are reported in DosError.
\SeeAlso
\seep{FindNext},
\seep{FindClose}
\end{procedure}

\FPCexample{ex7}

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

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

\FPCexample{ex10}

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

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

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

\FPCexample{ex12}

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

\var{GetCBreak} gets the status of CTRL-Break checking under \dos and \amiga.
When \var{BreakValue} is \var{false}, then \dos only checks for the 
CTRL-Break key-press when I/O is performed. When it is set to \var{True},
then a check is done at every system call.
\Portability
Under non-\dos and non-\amiga operating systems, \var{BreakValue} always returns 
\var{True}.
\Errors 
None
\SeeAlso
\seep{SetCBreak}
\end{procedure}

\begin{procedurel}{GetDate}{Dos:GetDate}
\Declaration
Procedure GetDate (var year, month, mday, wday: word);\Description

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

\FPCexample{ex2}

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

\var{Getenv} returns the value of the environment variable \var{EnvVar}.
When there is no environment variable \var{EnvVar} defined, an empty
string is returned.
\Portability
Under some operating systems (such as \unix), case is important when looking
for \var{EnvVar}.
\Errors
None.
\SeeAlso
\seef{EnvCount}, \seef{EnvStr}
\end{functionl}

\FPCexample{ex14}

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

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

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

\FPCexample{ex8}

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

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

\FPCexample{ex9}

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

\var{GetIntVec} returns the address of interrupt vector
\var{IntNo}.
\Portability
This call does nothing, it is present for compatibility only.
\Errors
None.
\SeeAlso
\seep{SetIntVec}
\end{procedure}

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

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

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

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

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

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

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

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

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

\var{GetTime} returns the system's time. \var{Hour} is a on a 24-hour time
scale. \var{sec100} is in hundredth of a
second.
\Portability
Certain operating systems (such as \amiga), always set the \var{sec100} field
to zero.
\Errors
None.
\SeeAlso
\seepl{GetDate}{Dos:GetDate},
\seep{SetTime}
\end{procedurel}


\FPCexample{ex3}


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

\var{GetVerify} returns the status of the verify flag under \dos. When
\var{Verify} is \var{True}, then \dos checks data which are written to disk,
by reading them after writing. If \var{Verify} is \var{False}, then data
written to disk are not verified.
\Portability
Under non-\dos systems (excluding \ostwo applications running under vanilla DOS),  
Verify is always \var{True}.
\Errors
None.
\SeeAlso
\seep{SetVerify}
\end{procedure}
\begin{procedure}{Intr}
\Declaration
Procedure Intr (IntNo: byte; var Regs: registers);
\Description

\var{Intr} executes a software interrupt number \var{IntNo} (must be between
0 and 255), with processor registers set to \var{Regs}. After the interrupt call
returned, the processor registers are saved in \var{Regs}.
\Portability
Under non-\dos operating systems, this call does nothing.
\Errors
None.
\SeeAlso
\seep{MSDos}, see the \linux unit.
\end{procedure}

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

\var{MSDos} executes an operating system. This is the same as doing a
\var{Intr} call with the interrupt number for an os call.
\Portability
Under non-\dos operating systems, this call does nothing. On \dos systems,
this calls interrupt \$21.
\Errors
None.
\SeeAlso
\seep{Intr}
\end{procedure}
\begin{procedure}{PackTime}
\Declaration
Procedure PackTime (var T: datetime; var P: longint);
\Description

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

\FPCexample{ex4}

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

\var{SetCBreak} sets the status of CTRL-Break checking. When 
\var{BreakValue} is \var{false}, then \dos only checks for the CTRL-Break 
key-press when I/O is performed. When it is set to \var{True}, then a 
check is done at every system call.
\Portability
Under non-\dos and non-\amiga operating systems, this call does nothing.
\Errors
None.
\SeeAlso
\seep{GetCBreak}
\end{procedure}
\begin{procedure}{SetDate}
\Declaration
Procedure SetDate (year,month,day: word);
\Description

\var{SetDate} sets the system's internal date. \var{Year} is a number
between 1980 and 2099.
\Portability
On a \linux machine, there must be root privileges, otherwise this
routine will do nothing. On other \unix systems, this call currently
does nothing.
\Errors
None.
\SeeAlso
\seep{Dos:GetDate},
\seep{SetTime}
\end{procedure}

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

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

\Portability
Under \unix like systems (such as \linux and \beos) the call exists, but is not implemented, 
i.e. it does nothing.
\Errors
Errors are reported in \var{DosError}.
\SeeAlso
\seep{GetFAttr}
\end{procedure}
\begin{procedure}{SetFTime}
\Declaration
Procedure SetFTime (var F; Time: longint);
\Description

\var{SetFTime} sets the modification time of a file,
this time is encoded and must be encoded with \var{PackTime}. 
\var{F} must be a file type, which has been assigned, and
opened.
\Portability
Under \unix like systems (such as \linux and \beos) the call exists, but is not implemented, 
i.e. it does nothing.
\Errors
Errors are reported in \var{DosError}
\SeeAlso
\seep{GetFTime}, \seep{PackTime},\seep{UnPackTime}
\end{procedure}

\begin{procedure}{SetIntVec}
\Declaration
Procedure SetIntVec (IntNo: byte; Vector: pointer);
\Description
\var{SetIntVec} sets interrupt vector \var{IntNo} to \var{Vector}.
\var{Vector} should point to an interrupt procedure.
\Portability
This call does nothing, it is present for compatibility only.
\Errors
None.
\SeeAlso
\seep{GetIntVec}
\end{procedure}

\begin{procedure}{SetTime}
\Declaration
Procedure SetTime (hour,minute,second,sec100: word);
\Description
\var{SetTime} sets the system's internal clock. The \var{Hour} parameter is
on a 24-hour time scale.
\Portability
On a \linux machine, there must be root privileges, otherwise this
routine will do nothing. On other \unix systems, this call currently
does nothing.
\Errors
None.
\SeeAlso
\seep{Dos:GetTime}, \seep{SetDate}
\end{procedure}
\begin{procedure}{SetVerify}
\Declaration
Procedure SetVerify (verify: boolean);
\Description

\var{SetVerify} sets the status of the verify flag under \dos. When
\var{Verify} is \var{True}, then \dos checks data which are written to disk,
by reading them after writing. If \var{Verify} is \var{False}, then data
written to disk are not verified.
\Portability
Under non-\dos operating systems (excluding \ostwo applications running
under vanilla dos), Verify is always \var{True}.
\Errors
None.
\SeeAlso
\seep{SetVerify}
\end{procedure}
\begin{procedure}{SwapVectors}
\Declaration
Procedure SwapVectors ;
\Description

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

\Portability
Under certain operating systems, this routine may be implemented
as an empty stub.
\Errors
None.
\SeeAlso
\seep{Exec}, \seep{SetIntVec}
\end{procedure}
\begin{procedure}{UnPackTime}
\Declaration
Procedure UnPackTime (p: longint; var T: datetime);
\Description

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