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 is the same for all operating systems.

Because the DOS unit is a Turbo Pascal compatibility unit, it is no longer actively developed: the interface is frozen and it is maintained only for the purpose of porting Turbo Pascal programs. For new development, it is recommended to use the sysutils unit instead.

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

End-of-line string TLineEndStr is used in the record to indicate the end-of-line sequence for a text file. Number of milliseconds since a starting point.

GetMSCount returns a number of milliseconds elapsed since a certain moment in time. This moment in time is implementation dependent. This function is used for timing purposes: Substracting the results of 2 subsequent calls to this function returns the number of milliseconds elapsed between the two calls.

This call is not very reliable, it is recommended to use some system specific calls for timings.

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)
Mode: File access mode (linux only)

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. This structure is only defined on a i386 compatible 32-bit platform, and is not used anywhere: it is defined for Turbo Pascal backwards compatibility only. 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. The program name should not appear again in ComLine, it is specified in Path. Comline contains only the parameters that are passed to the program.

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 and Win32 versions of Free Pascal.

GetLongName changes the filename p to a long filename if the API 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 API call was successful, False otherwise.

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

If the API 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 and Win32 versions of Free Pascal.

GetShortName changes the filename p to a short filename if the API 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 API call was successful, False otherwise.

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

If the API 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. Used for unix implementation Current search position Current search number Pointer to directory Type of search Attributes specified at findfirst. Padding bytes Attributes of the file. Timestamp of the file Size of the file Reserved for future use Name fo the file Wildcard specs specified at findfirst Name position AX register F1 register BX register F2 register CX register F3 register DX register F4 register BP register F5 register SI register F51 register DI register F6 register DS register F7 register ES register F8 register Flags FS register GS register AL register AH register F9 register F10 register BL register BH register F11 register F12 register CL register CH register F13 register F14 register DL register DH register EAX register EBX register ECX register EDX register EBP register ESI register EDI register File handle File open mode Size of buffer For internal use only buffer start position buffer end position Pointer to buffer File open function File IO function Data flush function File close function User data (reserved) File name Line ending in use Standard buffer File mode for Unix systems Mode contains the file mode as it exists in unix systems. See the baseunix unit for more information about the mode field.