DOS - Turbo Pascal MS-DOS interface

The 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 Klaempfl. It was ported to linux by Mark May and enhanced by Michael 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.

File attributes

The File Attribute constants are used in , to determine what type of special file to search for in addition to normal files. These flags are also used in the and routines to set and retrieve attributes of files. For their definitions consult .

Possible file attributes
| Constant | Description | Value
readonly |  | $01
hidden |  | $02
sysfile |  | $04
volumeid |  | $08
directory |  | $10
archive |  | $20
anyfile |  | $3F

File open mode constants.

These constants are used in the Mode field of the TextRec record. Gives information on the filemode of the text I/O. For their definitions consult the following table:

Possible mode constants
| Constant | Description | Value
fmclosed |  | $D7B0
fminput |  | $D7B1
fmoutput |  | $D7B2
fminout |  | $D7B3

File handling

Routines to handle files on disk.

| Name | Description
| Expand filename to full path
| Close finfirst/findnext session
| Start find of file
| Find next file
| Search for file in a path
| Split filename in parts
| Return file attributes
| Return file time
| Convert short filename to long filename (DOS only)
| Convert long filename to short filename (DOS only)
| Set file attributes
| Set file time

Directory and disk handling

Routines to handle disk information.

| Name | Description
| Add disk to list of disks (UNIX only)
| Return size of free disk space
| Return total disk size

Process handling

Functions to handle process information and starting new processes.

| Name | Description
| Exit code of last executed program
| Return number of environment variables
| Return environment string pair
| Execute program
| Return specified environment string

System information

Functions for retrieving and setting general system information such as date and time.

| Name | Description
| Get OS version
| Get setting of control-break handling flag
| Get system date
| Get interrupt vector status
| Get system time
| Get verify flag
| Execute an interrupt
| Keep process in memory and exit
| Execute MS-dos function call
| Pack time for file time
| Set control-break handling flag
| Set system date
| Set interrupt vectors
| Set system time
| Set verify flag
| Swap interrupt vectors
| Unpack file time

File is closed
File is read only
File is write only
File is read and write
CPU carry flag. Not used.
CPU parity flag. Not used.
CPU auxiliary flag. Not used.
CPU zero flag. Not used.
CPU sign flag. Not used.
CPU overflow flag. Not used.
Read-Only file attribute
Hidden file attribute
System file attribute
Volumd ID file attribute
Directory file attribute
Archive file attribute
Maximum length of a filename
Match any file attribute
Command-line string type
Full File path string type.
Full directory string type.
Fill filename string type.
Filename extension string type.
File Search Results record

SearchRec is filled by the call and can be used in subsequent calls to search for files. The structure of this record depends on the platform. Only the following fields are present on all platforms:

Attr
  File attributes.
Time
  File modification time.
Size
  File size
Name
  File name (name part only, no path)

Maximum length of FileName part in
Record describing an untyped file
FileRec
is used for internal representation of typed and untyped files.
OS file handle
File open mode
Size of a record (in bytes)
Private data, do not use
User data, for implementing a user driver.
File name
Maximum length of filename in
Size of default buffer in
Type for default buffer in
Record describing Text files

TextRec describes the internal working of a Text file.

Remark that this is not binary compatible with the Turbo Pascal definition of TextRec, since the sizes of the different fields are different.

OS file handle for this record
File open mode
Current buffer size.
Current buffer position.
Current length of data in buffer
Pointer tuo buffer.
Called when file needs to be opened.
Called when an I/O operation needs to be performed.
Called when buffer must be flushed.
Called when file must be closed.
Room for user data when implementing custom text file.
File name.
Default buffer.
Record to keep CPU registers for call. Unused.
Record containing a date/time description
The DateTime type is used in and for setting/reading file times with and .
Year part
Month of the year
Day of the month
Hour of the day
Minute of the hour
Second in the minute
Last OS (MS-DOS) error

The DosError variable is used by the procedures in the dos unit to report errors. It can have the following values :

Dos error codes
| Value | Meaning
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.

Other values are possible, but are not documented.

Pathnames representing drives.
This variable is defined in the linux version of the dos unit. It is used in the and calls.
Add disk definition to list if drives (Unix only)

AddDisk adds a filename 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 and calls. The and functions need a file on the specified drive, since this is required for the statfs system call. The names are added sequentially. The dos initialization code presets the first three disks to:

- '.'
  for the current drive,
- '/fd0/.'
  for the first floppy-drive (linux only).
- '/fd1/.'
  for the second floppy-drive (linux only).
- '/'
  for the first hard disk.

The first call to 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 'D:' to 'Z:')

None
Get free size on Disk.

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

For Unices: The diskfree and disksize functions need a file on the specified drive, since this is required for the statfs system call. These filenames are set in the initialization of the dos unit, and have been preset to :

- '.'
  for the current drive,
- '/fd0/.'
  for the first floppy-drive (linux only).
- '/fd1/.'
  for the second floppy-drive (linux only).
- '/'
  for the first hard disk.

There is room for 1-26 drives. You can add a drive with the procedure. These settings can be coded in dos.pp, in the initialization part.

-1 when a failure occurs, or an invalid drive number is given.
Get total size of disk.

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

For unix only: The diskfree and disksize functions need a file on the specified drive, since this is required for the statfs system call. These filenames are set in the initialization of the dos unit, and have been preset to :

- '.'
  for the current drive,
- '/fd0/.'
  for the first floppy-drive (linux only).
- '/fd1/.'
  for the second floppy-drive (linux only).
- '/'
  for the first hard disk.

There is room for 1-26 drives. You can add a drive with the procedure. These settings can be coded in dos.pp, in the initialization part.

For an example, see .

-1 when a failure occurs, or an invalid drive number is given.
Exit code of last executed program.
DosExitCode
contains (in the low byte) the exit-code of a program executed with the Exec call.
None.
Current OS version

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.

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.
None.
Return the number of environment variables
EnvCount
returns the number of environment variables.
None.
Return environment variable by index
EnvStr
returns the Index-th Name=Value pair from the list of environment variables. The index of the first pair is zero.
The length is limited to 255 characters.
Execute another program, and wait for it to finish.

Exec executes the program in Path, with the options given by ComLine.

After the program has terminated, the procedure returns. The Exit value of the program can be consulted with the DosExitCode function.

For an example, see

Errors are reported in DosError.
Expand a relative path to an absolute path

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

On case sensitive file systems (such as unix and linux), the resulting name is left as it is, otherwise it is converted to uppercase.
Dispose resources allocated by a / sequence.

FindClose frees any resources associated with the search record F.

This call is needed to free any internal resources allocated by the or calls.

The unix 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 searchrecs.

So, to speed up the findfirst/findnext system, the FindClose call was implemented. When you don't need a searchrec any more, you can tell this to the dos unit by issuing a FindClose call. The directory which is kept open for this searchrec is then closed, and the table slot freed.

It is recommended to use the linux call Glob when looking for files on linux.
Errors are reported in DosError.
Start search for one or more files.

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

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

On os/2, you cannot issue two different FindFirst calls. That is, you must close any previous search operation with before starting a new one. Failure to do so will end in a Run-Time Error 6 (Invalid file handle)
Errors are reported in DosError.
,
Find next matching file after

FindNext takes as an argument a SearchRec from a previous FindNext call, or a FindFirst call, and tries to find another file which matches the criteria, specified in the FindFirst call. If DosError is different from zero, no more files matching the criteria were found.

For an example, see .

DosError
is used to report errors.
Search a file in searchpath

FSearch searches the file Path in all directories listed in DirList. The full name of the found file is returned. DirList must be a list of directories, separated by semi-colons. When no file is found, an empty string is returned.

On unix systems, DirList can also be separated by colons, as is customary on those environments.
None.
FExpand
Split a full-path filename in parts.
FSplit
splits a full file name into 3 parts : A Path, a Name and an extension (in ext.) The extension is taken to be all letters after the last dot (.). For dos, however, an exception is made when LFNSupport=False, then the extension is defined as all characters after the first dot.
None.
FSearch
Get control-Break flag

GetCBreak gets the status of CTRL-Break checking under dos and Amiga. When BreakValue is false, then dos only checks for the CTRL-Break key-press when I/O is performed. When it is set to True, then a check is done at every system call.

Under non-dos and non-Amiga operating systems, BreakValue always returns True.
None
Get the current date
GetDate
returns the system's date. Year is a number in the range 1980..2099.mday is the day of the month, wday is the day of the week, starting with Sunday as day 0.
None.
Get environment variable by name.

Getenv returns the value of the environment variable EnvVar. When there is no environment variable EnvVar defined, an empty string is returned.

Under some operating systems (such as unix), case is important when looking for EnvVar.
None.
Get file attributes

GetFAttr returns the file attributes of the file-variable f. F can be a untyped or typed file, or of type Text. f must have been assigned, but not opened. The attributes can be examined with the following constants :

- ReadOnly
- Hidden
- SysFile
- VolumeId
- Directory
- Archive

Under linux, supported attributes are:

- Directory
- ReadOnly
  if the current process doesn't have access to the file.
- Hidden
  for files whose name starts with a dot ('.').

Errors are reported in DosError
Get file last modification time.
GetFTime
returns the modification time of a file. This time is encoded and must be decoded with UnPackTime. F must be a file type, which has been assigned, and opened.
Errors are reported in DosError
Get interrupt vector

GetIntVec returns the address of interrupt vector IntNo.

This call does nothing, it is present for compatibility only. Modern systems do not allow low level access to the hardware.
None.
Get the long filename of a DOS 8.3 filename.

This function is only implemented in the GO32V2 version of Free Pascal.

GetLongName changes the filename 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 p.

The function returns True if the dos call was successful, False otherwise.

This function should only be necessary when using the DOS extender under Windows 95 and higher.

If the dos call was not succesfull, False is returned.
Get the short (8.3) filename of a long filename.

This function is only implemented in the GO32V2 version of Free Pascal.

GetShortName changes the filename 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 p.

The function returns True if the dos call was successful, False otherwise.

This function should only be necessary when using the DOS extender under Windows 95 and higher.

If the dos call was not successful, False is returned.
Return the current time

GetTime returns the system's time. Hour is a on a 24-hour time scale. sec100 is in hundredth of a second.

Certain operating systems (such as Amiga), always set the sec100 field to zero.
None.
Get verify flag

GetVerify returns the status of the verify flag under dos. When Verify is True, then dos checks data which are written to disk, by reading them after writing. If Verify is False, then data written to disk are not verified.

Under non-dos systems (excluding os/2 applications running under vanilla DOS), Verify is always True.
None.
Execute interrupt

Intr executes a software interrupt number IntNo (must be between 0 and 255), with processor registers set to Regs. After the interrupt call returned, the processor registers are saved in Regs.

Under non-dos operating systems, this call does nothing.
None.
Terminate and stay resident.

Keep terminates the program, but stays in memory. This is used for TSR (Terminate Stay Resident) programs which catch some interrupt. ExitCode is the same parameter as the Halt function takes.

This call does nothing, it is present for compatibility only.
None.
Return the day of the week
WeekDay
returns the day of the week on which the day Y/M/D falls. Sunday is represented by 0, Saturday is 6.
On error, -1 is returned.
Convert a DateTime to unix timestamp
DTToUnixDate
converts the DateTime value in DT to a unix timestamp. It is an internal function, implemented on Unix platforms, and should not be used.
None.
Convert a unix timestamp to a DateTime record
DTToUnixDate
converts the unix timestamp value in SecsPast to a DateTime representation in DT. It is an internal function, implemented on Unix platforms, and should not be used.
None.
Execute MS-DOS system call

MSDos executes an operating system call. This is the same as doing a Intr call with the interrupt number for an os call.

Under non-dos operating systems, this call does nothing. On DOS systems, this calls interrupt $21.
None.
Pack DateTime value to a packed-time format.
UnPackTime
converts the date and time specified in T to a packed-time format which can be fed to SetFTime.
None.
Set Control-Break flag status

SetCBreak sets the status of CTRL-Break checking. When BreakValue is false, then dos only checks for the CTRL-Break key-press when I/O is performed. When it is set to True, then a check is done at every system call.

Under non-dos and non-Amiga operating systems, this call does nothing.
None.
Set system date

SetDate sets the system's internal date. Year is a number between 1980 and 2099.

On a unix machine, there must be root privileges, otherwise this routine will do nothing. On other unix systems, this call currently does nothing.
None.
Set file attributes

SetFAttr sets the file attributes of the file-variable F. F can be a untyped or typed file, or of type Text. F must have been assigned, but not opened. The attributes can be a sum of the following constants:

- ReadOnly
- Hidden
- SysFile
- VolumeId
- Directory
- Archive

Under unix like systems (such as linux and BeOS) the call exists, but is not implemented, i.e. it does nothing.
Errors are reported in DosError.
Set file modification time.

SetFTime sets the modification time of a file, this time is encoded and must be encoded with PackTime. F must be a file type, which has been assigned, and opened.

Under unix like systems (such as linux and BeOS) the call exists, but is not implemented, i.e. it does nothing.
Errors are reported in DosError
Set interrupt vector

SetIntVec sets interrupt vector IntNo to Vector. Vector should point to an interrupt procedure.

This call does nothing, it is present for compatibility only.
None.
Set system time

SetTime sets the system's internal clock. The Hour parameter is on a 24-hour time scale.

On a linux machine, there must be root privileges, otherwise this routine will do nothing. On other unix systems, this call currently does nothing.
None.
Set verify flag

SetVerify sets the status of the verify flag under dos. When Verify is True, then dos checks data which are written to disk, by reading them after writing. If Verify is False, then data written to disk are not verified.

Under non-dos operating systems (excluding os/2 applications running under vanilla dos), Verify is always True.
None.
Swap interrupt vectors

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 Exec call.

Under certain operating systems, this routine may be implemented as an empty stub.
None.
Unpack packed file time to a DateTime value

UnPackTime converts the file-modification time in p to a DateTime record. The file-modification time can be returned by GetFTime, FindFirst or FindNext calls.

For an example, see .

None.