1
<?xml version="1.0" encoding="ISO8859-1"?>
5
$Id: dos.xml,v 1.3 2005/03/16 07:54:10 michael Exp $
6
This file is part of the FPC documentation.
7
Copyright (C) 1997, by Michael Van Canneyt
9
The FPC documentation is free text; you can redistribute it and/or
10
modify it under the terms of the GNU Library General Public License as
11
published by the Free Software Foundation; either version 2 of the
12
License, or (at your option) any later version.
14
The FPC Documentation is distributed in the hope that it will be useful,
15
but WITHOUT ANY WARRANTY; without even the implied warranty of
16
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17
Library General Public License for more details.
19
You should have received a copy of the GNU Library General Public
20
License along with the FPC documentation; see the file COPYING.LIB. If not,
21
write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
22
Boston, MA 02111-1307, USA.
26
<short>DOS - Turbo Pascal MS-DOS interface</short>
27
<!-- \FPCexampledir{dosex} -->
30
The <file>DOS</file> unit gives access to some operating system calls
31
related to files, the file system, date and time. Except for the
32
PalmOS target, this unit is available to all supported platforms.
35
The unit was first written for dos by Florian Klaempfl. It was ported to
36
linux by Mark May and enhanced by Michael Van Canneyt.
37
The Amiga version was ported by Nils Sjoholm.
40
Under non-DOS systems, some of the functionality is lost, as it is either impossible
41
or meaningless to implement it. Other than that, the functionality for all
42
operating systems is the same.
46
<topic name="fileattributes">
47
<short>File attributes</short>
50
The File Attribute constants are used in <link id="FindFirst"/>,
51
<link id="FindNext"/> to
52
determine what type of special file to search for in addition to normal files.
53
These flags are also used in the <link id="SetFAttr"/> and <link id="GetFAttr"/> routines to
54
set and retrieve attributes of files. For their definitions consult
55
<link id="fileattributes"/>.
58
<caption>Possible file attributes</caption>
59
<th><td>Constant</td><td>Description</td><td>Value</td></th>
60
<tr><td><var>readonly</var></td><td><printshort id="readonly"/></td><td> $01</td></tr>
61
<tr><td><var>hidden</var> </td><td> <printshort id="hidden"/> </td><td> $02 </td></tr>
62
<tr><td><var>sysfile</var> </td><td> <printshort id="sysfile"/> </td><td> $04</td></tr>
63
<tr><td><var>volumeid</var> </td><td> <printshort id="volumeid"/> </td><td> $08</td></tr>
64
<tr><td><var>directory</var> </td><td> <printshort id="directory"/> </td><td> $10</td></tr>
65
<tr><td><var>archive</var> </td><td> <printshort id="archive"/> </td><td> $20</td></tr>
66
<tr><td><var>anyfile</var> </td><td> <printshort id="anyfile"/> </td><td> $3F</td></tr>
71
<topic name="filemodes">
72
<short>File open mode constants.</short>
75
These constants are used in the <var>Mode</var> field of the <var>TextRec</var>
76
record. Gives information on the filemode of the text I/O. For their
77
definitions consult the following table:
80
<caption>Possible mode constants</caption>
81
<th><td>Constant</td><td>Description</td><td>Value</td></th>
82
<tr><td><var>fmclosed</var></td><td><printshort id="fmclosed"/></td><td>$D7B0</td></tr>
83
<tr><td><var>fminput</var></td><td><printshort id="fminput"/></td><td>$D7B1 </td></tr>
84
<tr><td><var>fmoutput</var></td><td><printshort id="fmoutput"/></td><td>$D7B2</td></tr>
85
<tr><td><var>fminout</var></td><td><printshort id="fminout"/></td><td>$D7B3</td></tr>
90
<topic name="filehandling">
91
<short>File handling</short>
94
Routines to handle files on disk.
97
<th><td>Name</td><td>Description</td></th>
98
<tr><td><link id="FExpand"/></td><td>Expand filename to full path</td></tr>
99
<tr><td><link id="FindClose"/></td><td>Close finfirst/findnext session</td></tr>
100
<tr><td><link id="FindFirst"/></td><td>Start find of file</td></tr>
101
<tr><td><link id="FindNext"/></td><td>Find next file</td></tr>
102
<tr><td><link id="FSearch"/></td><td>Search for file in a path</td></tr>
103
<tr><td><link id="FSplit"/></td><td>Split filename in parts</td></tr>
104
<tr><td><link id="GetFAttr"/></td><td>Return file attributes</td></tr>
105
<tr><td><link id="GetFTime"/></td><td>Return file time</td></tr>
106
<tr><td><link id="GetLongName"/></td><td>Convert short filename to long filename (DOS only)</td></tr>
107
<tr><td><link id="GetShortName"/></td><td>Convert long filename to short filename (DOS only)</td></tr>
108
<tr><td><link id="SetFAttr"/></td><td>Set file attributes</td></tr>
109
<tr><td><link id="SetFTime"/></td><td>Set file time</td></tr>
114
<topic name="diskhandling">
115
<short>Directory and disk handling</short>
118
Routines to handle disk information.
121
<th><td>Name</td><td>Description</td></th>
122
<tr><td><link id="AddDisk"/></td><td>Add disk to list of disks (UNIX only)</td></tr>
123
<tr><td><link id="DiskFree"/></td><td>Return size of free disk space</td></tr>
124
<tr><td><link id="DiskSize"/></td><td>Return total disk size</td></tr>
129
<topic name="process">
130
<short>Process handling</short>
133
Functions to handle process information and starting new processes.
136
<th><td>Name</td><td>Description</td></th>
137
<tr><td><link id="DosExitCode"/></td><td>Exit code of last executed program</td></tr>
138
<tr><td><link id="EnvCount"/></td><td>Return number of environment variables</td></tr>
139
<tr><td><link id="EnvStr"/></td><td>Return environment string pair</td></tr>
140
<tr><td><link id="Exec"/></td><td>Execute program</td></tr>
141
<tr><td><link id="GetEnv"/></td><td>Return specified environment string</td></tr>
146
<topic name="sysinfo">
147
<short>System information</short>
150
Functions for retrieving and setting general system information such as date
154
<th><td>Name</td><td>Description</td></th>
155
<tr><td><link id="DosVersion"/></td><td>Get OS version</td></tr>
156
<tr><td><link id="GetCBreak"/></td><td>Get setting of control-break handling flag</td></tr>
157
<tr><td><link id="GetDate"/></td><td>Get system date</td></tr>
158
<tr><td><link id="GetIntVec"/></td><td>Get interrupt vector status</td></tr>
159
<tr><td><link id="GetTime"/></td><td>Get system time</td></tr>
160
<tr><td><link id="GetVerify"/></td><td>Get verify flag</td></tr>
161
<tr><td><link id="Intr"/></td><td>Execute an interrupt</td></tr>
162
<tr><td><link id="Keep"/></td><td>Keep process in memory and exit</td></tr>
163
<tr><td><link id="MSDos"/></td><td>Execute MS-dos function call</td></tr>
164
<tr><td><link id="PackTime"/></td><td>Pack time for file time</td></tr>
165
<tr><td><link id="SetCBreak"/></td><td>Set control-break handling flag</td></tr>
166
<tr><td><link id="SetDate"/></td><td>Set system date</td></tr>
167
<tr><td><link id="SetIntVec"/></td><td>Set interrupt vectors</td></tr>
168
<tr><td><link id="SetTime"/></td><td>Set system time</td></tr>
169
<tr><td><link id="SetVerify"/></td><td>Set verify flag</td></tr>
170
<tr><td><link id="SwapVectors"/></td><td>Swap interrupt vectors</td></tr>
171
<tr><td><link id="UnPackTime"/></td><td>Unpack file time</td></tr>
176
<element name="TLineEndStr">
177
<short>End-of-line string</short>
179
<var>TLineEndStr</var> is used in the <link id="TextRec"/> record to
180
indicate the end-of-line sequence for a text file.
184
<element name="GetMSCount">
185
<short>Number of milliseconds since a starting point.</short>
188
<var>GetMSCount</var> returns a number of milliseconds elapsed since a
189
certain moment in time. This moment in time is implementation dependent.
190
This function is used for timing purposes: Substracting the results of 2
191
subsequent calls to this function returns the number of milliseconds elapsed
192
between the two calls.
195
This call is not very reliable, it is recommended to use some system
196
specific calls for timings.
204
<element name="fmclosed">
205
<short>File is closed</short>
208
<element name="fminput">
209
<short>File is read only</short>
212
<element name="fmoutput">
213
<short>File is write only</short>
216
<element name="fminout">
217
<short>File is read and write</short>
220
<element name="fcarry">
221
<short>CPU carry flag. Not used.</short>
224
<element name="fparity">
225
<short>CPU parity flag. Not used.</short>
228
<element name="fauxiliary">
229
<short>CPU auxiliary flag. Not used.</short>
232
<element name="fzero">
233
<short>CPU zero flag. Not used.</short>
236
<element name="fsign">
237
<short>CPU sign flag. Not used.</short>
240
<element name="foverflow">
241
<short>CPU overflow flag. Not used.</short>
244
<element name="readonly">
245
<short>Read-Only file attribute</short>
248
<element name="hidden">
249
<short>Hidden file attribute</short>
252
<element name="sysfile">
253
<short>System file attribute</short>
256
<element name="volumeid">
257
<short>Volumd ID file attribute</short>
260
<element name="directory">
261
<short>Directory file attribute</short>
264
<element name="archive">
265
<short>Archive file attribute</short>
268
<element name="FileNameLen">
269
<short>Maximum length of a filename</short>
272
<element name="anyfile">
273
<short>Match any file attribute</short>
276
<element name="ComStr">
277
<short>Command-line string type</short>
280
<element name="PathStr">
281
<short>Full File path string type.</short>
284
<element name="DirStr">
285
<short>Full directory string type.</short>
288
<element name="NameStr">
289
<short>Fill filename string type.</short>
292
<element name="ExtStr">
293
<short>Filename extension string type.</short>
296
<element name="SearchRec">
297
<short>File Search Results record</short>
300
<var>SearchRec</var> is filled by the <link id="FindFirst"/> call and can be
301
used in subsequent <link id="FindNext"/> calls to search for files. The
302
structure of this record depends on the platform. Only the following
303
fields are present on all platforms:
306
<dt>Attr</dt><dd>File attributes.</dd>
307
<dt>Time</dt><dd>File modification time.</dd>
308
<dt>Size</dt><dd>File size</dd>
309
<dt>Name</dt><dd>File name (name part only, no path)</dd>
314
<element name="filerecnamelength">
315
<short>Maximum length of FileName part in <link id="FileRec"/></short>
318
<element name="FileRec">
319
<short>Record describing an untyped file</short>
321
<var>FileRec</var> is used for internal representation of typed and untyped files.
325
<element name="FileRec.Handle">
326
<short>OS file handle</short>
329
<element name="FileRec.Mode">
330
<short>File open mode</short>
333
<element name="FileRec.RecSize">
334
<short>Size of a record (in bytes)</short>
337
<element name="FileRec._Private">
338
<short>Private data, do not use</short>
341
<element name="FileRec.UserData">
342
<short>User data, for implementing a user driver.</short>
345
<element name="FileRec.Name">
346
<short>File name</short>
349
<element name="TextRecNameLength">
350
<short>Maximum length of filename in <link id="TextRec"/></short>
353
<element name="TextRecBufSize">
354
<short>Size of default buffer in <link id="TextRec"/></short>
357
<element name="TextBuf">
358
<short>Type for default buffer in <link id="TextRec"/></short>
361
<element name="TextRec">
362
<short>Record describing Text files</short>
365
<var>TextRec</var> describes the internal working of a <var>Text</var> file.
368
Remark that this is not binary compatible with the Turbo Pascal definition
369
of <var>TextRec</var>, since the sizes of the different fields are different.
374
<element name="Handle">
375
<short>OS file handle for this record</short>
378
<element name="Mode">
379
<short>File open mode</short>
382
<element name="bufsize">
383
<short>Current buffer size.</short>
386
<element name="bufpos">
387
<short>Current buffer position.</short>
390
<element name="bufend">
391
<short>Current length of data in buffer</short>
394
<element name="bufptr">
395
<short>Pointer tuo buffer.</short>
398
<element name="openfunc">
399
<short>Called when file needs to be opened.</short>
402
<element name="inoutfunc">
403
<short>Called when an I/O operation needs to be performed.</short>
406
<element name="flushfunc">
407
<short>Called when buffer must be flushed.</short>
410
<element name="closefunc">
411
<short>Called when file must be closed.</short>
414
<element name="UserData">
415
<short>Room for user data when implementing custom text file.</short>
418
<element name="name">
419
<short>File name.</short>
422
<element name="buffer">
423
<short>Default buffer.</short>
426
<element name="Registers">
427
<short>Record to keep CPU registers for <link id="MSDos"/> call. Unused.</short>
429
<element name="DateTime">
430
<short>Record containing a date/time description</short>
432
The <var>DateTime</var> type is used in <link id="PackTime"/> and <link id="UnPackTime"/> for
433
setting/reading file times with <link id="GetFTime"/> and <link id="SetFTime"/>.
437
<element name="DateTime.Year">
438
<short>Year part</short>
440
<element name="DateTime.Month">
441
<short>Month of the year</short>
443
<element name="DateTime.Day">
444
<short>Day of the month</short>
446
<element name="DateTime.Hour">
447
<short>Hour of the day</short>
449
<element name="DateTime.Min">
450
<short>Minute of the hour</short>
452
<element name="DateTime.Sec">
453
<short>Second in the minute</short>
456
<element name="DosError">
457
<short>Last OS (MS-DOS) error</short>
460
The <var>DosError</var> variable is used by the procedures in the dos unit to
461
report errors. It can have the following values :
464
<caption>Dos error codes</caption>
465
<th><td>Value</td><td>Meaning</td></th>
466
<tr><td>2 </td><td> File not found. </td></tr>
467
<tr><td>3 </td><td> path not found. </td></tr>
468
<tr><td>5 </td><td> Access denied. </td></tr>
469
<tr><td>6 </td><td> Invalid handle. </td></tr>
470
<tr><td>8 </td><td> Not enough memory. </td></tr>
471
<tr><td>10 </td><td> Invalid environment. </td></tr>
472
<tr><td>11 </td><td> Invalid format. </td></tr>
473
<tr><td>18 </td><td> No more files.</td></tr>
476
Other values are possible, but are not documented.
481
<element name="drivestr">
482
<short>Pathnames representing drives.</short>
484
This variable is defined in the linux version of the dos unit. It is used
485
in the <link id="DiskFree"/> and <link id="DiskSize"/> calls.
489
<element name="AddDisk">
490
<short>Add disk definition to list if drives (Unix only)</short>
493
<var>AddDisk</var> adds a filename <var>S</var> to the internal list of disks. It is
494
implemented for systems which do not use DOS type drive letters.
495
This list is used to determine which disks to use in the <link id="DiskFree"/>
496
and <link id="DiskSize"/> calls.
497
The <link id="DiskFree"/> and <link id="DiskSize"/> functions need a file on the
498
specified drive, since this is required for the <var>statfs</var> system call.
499
The names are added sequentially. The dos
500
initialization code presets the first three disks to:
503
<li> <var>'.'</var> for the current drive, </li>
504
<li> <var>'/fd0/.'</var> for the first floppy-drive (linux only).</li>
505
<li> <var>'/fd1/.'</var> for the second floppy-drive (linux only).</li>
506
<li> <var>'/'</var> for the first hard disk.</li>
509
The first call to <var>AddDisk</var> will therefore add a name for the second
510
harddisk, The second call for the third drive, and so on until 23 drives
511
have been added (corresponding to drives <var>'D:'</var> to <var>'Z:'</var>)
518
<link id="DiskFree"/>
519
<link id="DiskSize"/>
524
<element name="DiskFree">
525
<short>Get free size on Disk.</short>
528
<var>DiskFree</var> returns the number of free bytes on a disk. The parameter
529
<var>Drive</var> indicates which disk should be checked. This parameter is 1 for
530
floppy <var>a:</var>, 2 for floppy <var>b:</var>, etc. A value of 0 returns the free
531
space on the current drive.
535
The <var>diskfree</var> and <var>disksize</var> functions need a file on the
536
specified drive, since this is required for the <var>statfs</var> system call.
537
These filenames are set in the initialization of the dos unit, and have
541
<li> <var>'.'</var> for the current drive, </li>
542
<li> <var>'/fd0/.'</var> for the first floppy-drive (linux only).</li>
543
<li> <var>'/fd1/.'</var> for the second floppy-drive (linux only).</li>
544
<li> <var>'/'</var> for the first hard disk.</li>
547
There is room for 1-26 drives. You can add a drive with the
548
<link id="AddDisk"/> procedure.
549
These settings can be coded in <var>dos.pp</var>, in the initialization part.
553
-1 when a failure occurs, or an invalid drive number is given.
556
<link id="DiskSize"/>
559
<example file="dosex/ex6"/>
563
<element name="DiskSize">
564
<short>Get total size of disk.</short>
567
<var>DiskSize</var> returns the total size (in bytes) of a disk. The parameter
568
<var>Drive</var> indicates which disk should be checked. This parameter is 1 for
569
floppy <var>a:</var>, 2 for floppy <var>b:</var>, etc. A value of 0 returns the size
570
of the current drive.
574
The <var>diskfree</var> and <var>disksize</var> functions need a file on the specified drive, since this
575
is required for the <var>statfs</var> system call.
576
These filenames are set in the initialization of the dos unit, and have
580
<li> <var>'.'</var> for the current drive, </li>
581
<li> <var>'/fd0/.'</var> for the first floppy-drive (linux only).</li>
582
<li> <var>'/fd1/.'</var> for the second floppy-drive (linux only).</li>
583
<li> <var>'/'</var> for the first hard disk.</li>
586
There is room for 1-26 drives. You can add a drive with the
587
<link id="AddDisk"/> procedure.
588
These settings can be coded in <var>dos.pp</var>, in the initialization part.
591
For an example, see <link id="DiskFree"/>.
595
-1 when a failure occurs, or an invalid drive number is given.
598
<link id="DiskFree"/>
603
<element name="DosExitCode">
604
<short>Exit code of last executed program.</short>
606
<var>DosExitCode</var> contains (in the low byte) the exit-code of a program
607
executed with the <var>Exec</var> call.
615
<example file="dosex/ex5"/>
618
<element name="DosVersion">
619
<short>Current OS version</short>
622
<var>DosVersion</var> returns the operating system or kernel version. The
623
low byte contains the major version number, while the high byte
624
contains the minor version number.
627
On systems where versions consists of more then two numbers,
628
only the first two numbers will be returned. For example Linux version 2.1.76
629
will give you DosVersion 2.1. Some operating systems, such as FreeBSD, do not
630
have system calls to return the kernel version, in that case a value of 0 will
639
<example file="dosex/ex1"/>
642
<element name="EnvCount">
643
<short>Return the number of environment variables</short>
645
<var>EnvCount</var> returns the number of environment variables.
656
<element name="EnvStr">
657
<short>Return environment variable by index</short>
660
<var>EnvStr</var> returns the <var>Index</var>-th <var>Name=Value</var> pair from the list
661
of environment variables.
662
The index of the first pair is zero.
665
The length is limited to 255 characters.
668
<link id="EnvCount"/>
671
<example file="dosex/ex13"/>
675
<element name="Exec">
676
<short>Execute another program, and wait for it to finish.</short>
679
<var>Exec</var> executes the program in <var>Path</var>, with the options given by
680
<var>ComLine</var>. The program name should <em>not</em> appear again in
681
<var>ComLine</var>, it is specified in <var>Path</var>. Comline contains only the
682
parameters that are passed to the program.
685
After the program has terminated, the procedure returns. The Exit value of
686
the program can be consulted with the <var>DosExitCode</var> function.
689
For an example, see <link id="DosExitCode"/>
693
Errors are reported in <var>DosError</var>.
696
<link id="DosExitCode"/>
700
<element name="FExpand">
701
<short>Expand a relative path to an absolute path</short>
704
<var>FExpand</var> takes its argument and expands it to a complete filename, i.e.
705
a filename starting from the root directory of the current drive, prepended
706
with the drive-letter or volume name (when supported).
709
On case sensitive file systems (such as unix and linux), the resulting
710
name is left as it is, otherwise it is converted to uppercase.
718
<example file="dosex/ex11"/>
722
<element name="FindClose">
723
<short>Dispose resources allocated by a <link id="FindFirst"/>/<link
724
id="FindNext"/> sequence.</short>
727
<var>FindClose</var> frees any resources associated with the search record
731
This call is needed to free any internal resources allocated by the
732
<link id="FindFirst"/> or <link id="FindNext"/> calls.
735
The unix implementation of the dos unit therefore keeps a table of open
736
directories, and when the table is full, closes one of the directories, and
737
reopens another. This system is adequate but slow if you use a lot of
738
<var>searchrecs</var>.
741
So, to speed up the findfirst/findnext system, the <var>FindClose</var> call was
742
implemented. When you don't need a <var>searchrec</var> any more, you can tell
743
this to the dos unit by issuing a <var>FindClose</var> call. The directory
744
which is kept open for this <var>searchrec</var> is then closed, and the table slot
748
It is recommended to use the linux call <var>Glob</var> when looking for files
753
Errors are reported in DosError.
756
<link id="FindFirst"/>
757
<link id="FindNext"/>
761
<element name="FindFirst">
762
<short>Start search for one or more files.</short>
765
<var>FindFirst</var> searches the file specified in <var>Path</var>. Normal files,
766
as well as all special files which have the attributes specified in
767
<var>Attr</var> will be returned.
770
It returns a <var>SearchRec</var> record for further searching in <var>F</var>.
771
<var>Path</var> can contain the wildcard characters <var>?</var> (matches any single
772
character) and <var>*</var> (matches 0 ore more arbitrary characters). In this
773
case <var>FindFirst</var> will return the first file which matches the specified
775
If <var>DosError</var> is different from zero, no file(s) matching the criteria
779
On os/2, you cannot issue two different <var>FindFirst</var> calls. That is,
780
you must close any previous search operation with <link id="FindClose"/> before
781
starting a new one. Failure to do so will end in a Run-Time Error 6
782
(Invalid file handle)
786
Errors are reported in DosError.
789
<link id="FindNext"/>,
790
<link id="FindClose"/>
792
<example file="dosex/ex7"/>
796
<element name="FindNext">
797
<short>Find next matching file after <link id="FindFirst"/></short>
800
<var>FindNext</var> takes as an argument a <var>SearchRec</var> from a previous
801
<var>FindNext</var> call, or a <var>FindFirst</var> call, and tries to find another
802
file which matches the criteria, specified in the <var>FindFirst</var> call.
803
If <var>DosError</var> is different from zero, no more files matching the
807
For an example, see <link id="FindFirst"/>.
811
<var>DosError</var> is used to report errors.
814
<link id="FindFirst"/>
815
<link id="FindClose"/>
819
<element name="FSearch">
820
<short>Search a file in searchpath</short>
823
<var>FSearch</var> searches the file <var>Path</var> in all directories listed in
824
<var>DirList</var>. The full name of the found file is returned.
825
<var>DirList</var> must be a list of directories, separated by semi-colons.
826
When no file is found, an empty string is returned.
829
On unix systems, <var>DirList</var> can also be separated by colons, as is
830
customary on those environments.
837
<link id="FExpand">FExpand</link>
839
<example file="dosex/ex10"/>
844
<element name="FSplit">
845
<short>Split a full-path filename in parts.</short>
847
<var>FSplit</var> splits a full file name into 3 parts : A <var>Path</var>, a
848
<var>Name</var> and an extension (in <var>ext</var>.)
849
The extension is taken to be all letters after the <em> last</em> dot (.). For
850
dos, however, an exception is made when <var>LFNSupport=False</var>, then
851
the extension is defined as all characters after the <em> first</em> dot.
857
<link id="FSearch">FSearch</link>
859
<example file="dosex/ex12"/>
863
<element name="GetCBreak">
864
<short>Get control-Break flag</short>
867
<var>GetCBreak</var> gets the status of CTRL-Break checking under dos and Amiga.
868
When <var>BreakValue</var> is <var>false</var>, then dos only checks for the
869
CTRL-Break key-press when I/O is performed. When it is set to <var>True</var>,
870
then a check is done at every system call.
873
Under non-dos and non-Amiga operating systems, <var>BreakValue</var> always returns
881
<link id="SetCBreak"/>
885
<element name="GetDate">
886
<short>Get the current date</short>
888
<var>GetDate</var> returns the system's date. <var>Year</var> is a number in the range
889
1980..2099.<var>mday</var> is the day of the month,
890
<var>wday</var> is the day of the week, starting with Sunday as day 0.
899
<example file="dosex/ex2"/>
903
<element name="GetEnv">
904
<short>Get environment variable by name.</short>
907
<var>Getenv</var> returns the value of the environment variable <var>EnvVar</var>.
908
When there is no environment variable <var>EnvVar</var> defined, an empty
912
Under some operating systems (such as unix), case is important when looking
913
for <var>EnvVar</var>.
920
<link id="EnvCount"/>
923
<example file="dosex/ex14"/>
926
<element name="GetFAttr">
927
<short>Get file attributes</short>
930
<var>GetFAttr</var> returns the file attributes of the file-variable <var>f</var>.
931
<var>F</var> can be a untyped or typed file, or of type <var>Text</var>. <var>f</var> must
932
have been assigned, but not opened. The attributes can be examined with the
933
following constants :
936
<li> <var>ReadOnly</var></li>
937
<li> <var>Hidden</var></li>
938
<li> <var>SysFile</var></li>
939
<li> <var>VolumeId</var></li>
940
<li> <var>Directory</var></li>
941
<li> <var>Archive</var></li>
944
Under linux, supported attributes are:
947
<li> <var>Directory</var></li>
948
<li> <var>ReadOnly</var> if the current process doesn't have access to the file.</li>
949
<li> <var>Hidden</var> for files whose name starts with a dot <var>('.')</var>.</li>
953
Errors are reported in <var>DosError</var>
956
<link id="SetFAttr"/>
958
<example file="dosex/ex8"/>
962
<element name="GetFTime">
963
<short>Get file last modification time.</short>
965
<var>GetFTime</var> returns the modification time of a file.
966
This time is encoded and must be decoded with <var>UnPackTime</var>.
967
<var>F</var> must be a file type, which has been assigned, and
971
Errors are reported in <var>DosError</var>
974
<link id="SetFTime"/>
975
<link id="PackTime"/>
976
<link id="UnPackTime"/>
978
<example file="dosex/ex9"/>
982
<element name="GetIntVec">
983
<short>Get interrupt vector</short>
986
<var>GetIntVec</var> returns the address of interrupt vector
990
This call does nothing, it is present for compatibility only. Modern systems
991
do not allow low level access to the hardware.
998
<link id="SetIntVec"/>
1002
<element name="GetLongName">
1003
<short>Get the long filename of a DOS 8.3 filename.</short>
1006
This function is only implemented in the GO32V2 and Win32 versions of Free Pascal.
1009
<var>GetLongName</var> changes the filename <var>p</var> to a long filename
1010
if the API call to do this is successful. The resulting string
1011
is the long file name corresponding to the short filename <var>p</var>.
1014
The function returns <var>True</var> if the API call was successful,
1015
<var>False</var> otherwise.
1018
This function should only be necessary when using the DOS extender
1019
under Windows 95 and higher.
1023
If the API call was not succesfull, <var>False</var> is returned.
1026
<link id="GetShortName"/>
1030
<element name="GetShortName">
1031
<short>Get the short (8.3) filename of a long filename.</short>
1034
This function is only implemented in the GO32V2 and Win32 versions of Free Pascal.
1037
<var>GetShortName</var> changes the filename <var>p</var> to a short filename
1038
if the API call to do this is successful. The resulting string
1039
is the short file name corresponding to the long filename <var>p</var>.
1042
The function returns <var>True</var> if the API call was successful,
1043
<var>False</var> otherwise.
1046
This function should only be necessary when using the DOS extender
1047
under Windows 95 and higher.
1051
If the API call was not successful, <var>False</var> is returned.
1054
<link id="GetLongName"/>
1058
<element name="GetTime">
1059
<short>Return the current time</short>
1062
<var>GetTime</var> returns the system's time. <var>Hour</var> is a on a 24-hour time
1063
scale. <var>sec100</var> is in hundredth of a
1067
Certain operating systems (such as Amiga), always set the <var>sec100</var> field
1075
<link id="GetDate"/>
1076
<link id="SetTime"/>
1078
<example file="dosex/ex3"/>
1082
<element name="GetVerify">
1083
<short>Get verify flag</short>
1086
<var>GetVerify</var> returns the status of the verify flag under dos. When
1087
<var>Verify</var> is <var>True</var>, then dos checks data which are written to disk,
1088
by reading them after writing. If <var>Verify</var> is <var>False</var>, then data
1089
written to disk are not verified.
1092
Under non-dos systems (excluding os/2 applications running under vanilla DOS),
1093
Verify is always <var>True</var>.
1100
<link id="SetVerify"/>
1104
<element name="Intr">
1105
<short>Execute interrupt</short>
1108
<var>Intr</var> executes a software interrupt number <var>IntNo</var> (must be between
1109
0 and 255), with processor registers set to <var>Regs</var>. After the interrupt call
1110
returned, the processor registers are saved in <var>Regs</var>.
1113
Under non-dos operating systems, this call does nothing.
1124
<element name="Keep">
1125
<short>Terminate and stay resident.</short>
1128
<var>Keep</var> terminates the program, but stays in memory. This is used for TSR
1129
(Terminate Stay Resident) programs which catch some interrupt.
1130
<var>ExitCode</var> is the same parameter as the <var>Halt</var> function takes.
1133
This call does nothing, it is present for compatibility only.
1143
<element name="weekday">
1144
<short>Return the day of the week</short>
1146
<var>WeekDay</var> returns the day of the week on which the day
1147
<var>Y/M/D</var> falls. Sunday is represented by 0, Saturday is 6.
1150
On error, -1 is returned.
1153
<link id="PackTime"/>
1154
<link id="UnpackTime"/>
1155
<link id="GetTime"/>
1156
<link id="SetTime"/>
1160
<element name="DTToUnixDate">
1161
<short>Convert a DateTime to unix timestamp</short>
1163
<var>DTToUnixDate</var> converts the DateTime value in <var>DT</var> to a
1164
unix timestamp. It is an internal function, implemented on Unix platforms,
1165
and should not be used.
1171
<link id="UnixDateToDT"/>
1172
<link id="PackTime"/>
1173
<link id="UnpackTime"/>
1174
<link id="GetTime"/>
1175
<link id="SetTime"/>
1179
<element name="UnixDateToDT">
1180
<short>Convert a unix timestamp to a DateTime record </short>
1182
<var>DTToUnixDate</var> converts the unix timestamp value in <var>SecsPast</var> to a
1183
DateTime representation in <var>DT</var>. It is an internal function, implemented on Unix platforms,
1184
and should not be used.
1190
<link id="DTToUnixDate"/>
1191
<link id="PackTime"/>
1192
<link id="UnpackTime"/>
1193
<link id="GetTime"/>
1194
<link id="SetTime"/>
1199
<element name="MSDos">
1200
<short>Execute MS-DOS system call</short>
1203
<var>MSDos</var> executes an operating system call. This is the same as doing a
1204
<var>Intr</var> call with the interrupt number for an os call.
1207
Under non-dos operating systems, this call does nothing. On DOS systems,
1208
this calls interrupt $21.
1219
<element name="PackTime">
1220
<short>Pack DateTime value to a packed-time format.</short>
1222
<var>UnPackTime</var> converts the date and time specified in <var>T</var>
1223
to a packed-time format which can be fed to <var>SetFTime</var>.
1229
<link id="SetFTime"/>
1230
<link id="FindFirst"/>
1231
<link id="FindNext"/>
1232
<link id="UnPackTime"/>
1234
<example file="dosex/ex4"/>
1238
<element name="SetCBreak">
1239
<short>Set Control-Break flag status</short>
1242
<var>SetCBreak</var> sets the status of CTRL-Break checking. When
1243
<var>BreakValue</var> is <var>false</var>, then dos only checks for the CTRL-Break
1244
key-press when I/O is performed. When it is set to <var>True</var>, then a
1245
check is done at every system call.
1248
Under non-dos and non-Amiga operating systems, this call does nothing.
1255
<link id="GetCBreak"/>
1259
<element name="SetDate">
1260
<short>Set system date</short>
1263
<var>SetDate</var> sets the system's internal date. <var>Year</var> is a number
1264
between 1980 and 2099.
1267
On a unix machine, there must be root privileges, otherwise this
1268
routine will do nothing. On other unix systems, this call currently
1276
<link id="GetDate"/>
1277
<link id="SetTime"/>
1281
<element name="SetFAttr">
1282
<short>Set file attributes</short>
1285
<var>SetFAttr</var> sets the file attributes of the file-variable <var>F</var>.
1286
<var>F</var> can be a untyped or typed file, or of type <var>Text</var>. <var>F</var> must
1287
have been assigned, but not opened. The attributes can be a sum of the
1288
following constants:
1291
<li> <var>ReadOnly</var></li>
1292
<li> <var>Hidden</var></li>
1293
<li> <var>SysFile</var></li>
1294
<li> <var>VolumeId</var></li>
1295
<li> <var>Directory</var></li>
1296
<li> <var>Archive</var></li>
1299
Under unix like systems (such as linux and BeOS) the call exists, but is not implemented,
1300
i.e. it does nothing.
1304
Errors are reported in <var>DosError</var>.
1307
<link id="GetFAttr"/>
1312
<element name="SetFTime">
1313
<short>Set file modification time.</short>
1316
<var>SetFTime</var> sets the modification time of a file,
1317
this time is encoded and must be encoded with <var>PackTime</var>.
1318
<var>F</var> must be a file type, which has been assigned, and
1322
Under unix like systems (such as linux and BeOS) the call exists, but is not implemented,
1323
i.e. it does nothing.
1327
Errors are reported in <var>DosError</var>
1330
<link id="GetFTime"/>
1331
<link id="PackTime"/>
1332
<link id="UnPackTime"/>
1336
<element name="SetIntVec">
1337
<short>Set interrupt vector</short>
1340
<var>SetIntVec</var> sets interrupt vector <var>IntNo</var> to <var>Vector</var>.
1341
<var>Vector</var> should point to an interrupt procedure.
1344
This call does nothing, it is present for compatibility only.
1351
<link id="GetIntVec"/>
1355
<element name="SetTime">
1356
<short>Set system time</short>
1359
<var>SetTime</var> sets the system's internal clock. The <var>Hour</var> parameter is
1360
on a 24-hour time scale.
1363
On a linux machine, there must be root privileges, otherwise this
1364
routine will do nothing. On other unix systems, this call currently
1372
<link id="GetTime"/>
1373
<link id="SetDate"/>
1377
<element name="SetVerify">
1378
<short>Set verify flag</short>
1381
<var>SetVerify</var> sets the status of the verify flag under dos. When
1382
<var>Verify</var> is <var>True</var>, then dos checks data which are written to disk,
1383
by reading them after writing. If <var>Verify</var> is <var>False</var>, then data
1384
written to disk are not verified.
1387
Under non-dos operating systems (excluding os/2 applications running
1388
under vanilla dos), Verify is always <var>True</var>.
1395
<link id="SetVerify"/>
1399
<element name="SwapVectors">
1400
<short>Swap interrupt vectors</short>
1403
<var>SwapVectors</var> swaps the contents of the internal table of interrupt
1404
vectors with the current contents of the interrupt vectors.
1405
This is called typically in before and after an <var>Exec</var> call.
1408
Under certain operating systems, this routine may be implemented
1417
<link id="SetIntVec"/>
1421
<element name="UnPackTime">
1422
<short>Unpack packed file time to a DateTime value</short>
1425
<var>UnPackTime</var> converts the file-modification time in <var>p</var>
1426
to a <var>DateTime</var> record. The file-modification time can be
1427
returned by <var>GetFTime</var>, <var>FindFirst</var> or <var>FindNext</var> calls.
1430
For an example, see <link id="PackTime"/>.
1437
<link id="GetFTime"/>
1438
<link id="FindFirst"/>
1439
<link id="FindNext"/>
1440
<link id="PackTime"/>
1444
<!-- unresolved type reference Visibility: default -->
1445
<element name="baseunix">
1446
<short>Used for unix implementation</short>
1449
<!-- variable Visibility: default -->
1450
<element name="SearchRec.SearchPos">
1451
<short>Current search position</short>
1454
<!-- variable Visibility: default -->
1455
<element name="SearchRec.SearchNum">
1456
<short>Current search number</short>
1459
<!-- variable Visibility: default -->
1460
<element name="SearchRec.DirPtr">
1461
<short>Pointer to directory</short>
1464
<!-- variable Visibility: default -->
1465
<element name="SearchRec.SearchType">
1466
<short>Type of search</short>
1469
<!-- variable Visibility: default -->
1470
<element name="SearchRec.SearchAttr">
1471
<short>Attributes specified at findfirst.</short>
1474
<!-- variable Visibility: default -->
1475
<element name="SearchRec.Fill">
1476
<short>Padding bytes</short>
1479
<!-- variable Visibility: default -->
1480
<element name="SearchRec.Attr">
1481
<short>Attributes of the file.</short>
1484
<!-- variable Visibility: default -->
1485
<element name="SearchRec.Time">
1486
<short>Timestamp of the file</short>
1489
<!-- variable Visibility: default -->
1490
<element name="SearchRec.Size">
1491
<short>Size of the file</short>
1494
<!-- variable Visibility: default -->
1495
<element name="SearchRec.Reserved">
1496
<short>Reserved for future use</short>
1499
<!-- variable Visibility: default -->
1500
<element name="SearchRec.Name">
1501
<short>Name fo the file</short>
1504
<!-- variable Visibility: default -->
1505
<element name="SearchRec.SearchSpec">
1506
<short>Wildcard specs specified at findfirst</short>
1509
<!-- variable Visibility: default -->
1510
<element name="SearchRec.NamePos">
1511
<short>Name position</short>
1514
<!-- variable Visibility: default -->
1515
<element name="Registers.ax">
1516
<short>AX register</short>
1519
<!-- variable Visibility: default -->
1520
<element name="Registers.f1">
1521
<short>F1 register</short>
1524
<!-- variable Visibility: default -->
1525
<element name="Registers.bx">
1526
<short>BX register</short>
1529
<!-- variable Visibility: default -->
1530
<element name="Registers.f2">
1531
<short>F2 register</short>
1534
<!-- variable Visibility: default -->
1535
<element name="Registers.cx">
1536
<short>CX register</short>
1539
<!-- variable Visibility: default -->
1540
<element name="Registers.f3">
1541
<short>F3 register</short>
1544
<!-- variable Visibility: default -->
1545
<element name="Registers.dx">
1546
<short>DX register</short>
1549
<!-- variable Visibility: default -->
1550
<element name="Registers.f4">
1551
<short>F4 register</short>
1554
<!-- variable Visibility: default -->
1555
<element name="Registers.bp">
1556
<short>BP register</short>
1559
<!-- variable Visibility: default -->
1560
<element name="Registers.f5">
1561
<short>F5 register</short>
1564
<!-- variable Visibility: default -->
1565
<element name="Registers.si">
1566
<short>SI register</short>
1569
<!-- variable Visibility: default -->
1570
<element name="Registers.f51">
1571
<short>F51 register</short>
1574
<!-- variable Visibility: default -->
1575
<element name="Registers.di">
1576
<short>DI register</short>
1579
<!-- variable Visibility: default -->
1580
<element name="Registers.f6">
1581
<short>F6 register</short>
1584
<!-- variable Visibility: default -->
1585
<element name="Registers.ds">
1586
<short>DS register</short>
1589
<!-- variable Visibility: default -->
1590
<element name="Registers.f7">
1591
<short>F7 register</short>
1594
<!-- variable Visibility: default -->
1595
<element name="Registers.es">
1596
<short>ES register</short>
1599
<!-- variable Visibility: default -->
1600
<element name="Registers.f8">
1601
<short>F8 register</short>
1604
<!-- variable Visibility: default -->
1605
<element name="Registers.flags">
1606
<short>Flags</short>
1609
<!-- variable Visibility: default -->
1610
<element name="Registers.fs">
1611
<short>FS register</short>
1614
<!-- variable Visibility: default -->
1615
<element name="Registers.gs">
1616
<short>GS register</short>
1619
<!-- variable Visibility: default -->
1620
<element name="Registers.al">
1621
<short>AL register</short>
1624
<!-- variable Visibility: default -->
1625
<element name="Registers.ah">
1626
<short>AH register</short>
1629
<!-- variable Visibility: default -->
1630
<element name="Registers.f9">
1631
<short>F9 register</short>
1634
<!-- variable Visibility: default -->
1635
<element name="Registers.f10">
1636
<short>F10 register</short>
1639
<!-- variable Visibility: default -->
1640
<element name="Registers.bl">
1641
<short>BL register</short>
1644
<!-- variable Visibility: default -->
1645
<element name="Registers.bh">
1646
<short>BH register</short>
1649
<!-- variable Visibility: default -->
1650
<element name="Registers.f11">
1651
<short>F11 register</short>
1654
<!-- variable Visibility: default -->
1655
<element name="Registers.f12">
1656
<short>F12 register</short>
1659
<!-- variable Visibility: default -->
1660
<element name="Registers.cl">
1661
<short>CL register</short>
1664
<!-- variable Visibility: default -->
1665
<element name="Registers.ch">
1666
<short>CH register</short>
1669
<!-- variable Visibility: default -->
1670
<element name="Registers.f13">
1671
<short>F13 register</short>
1674
<!-- variable Visibility: default -->
1675
<element name="Registers.f14">
1676
<short>F14 register</short>
1679
<!-- variable Visibility: default -->
1680
<element name="Registers.dl">
1681
<short>DL register</short>
1684
<!-- variable Visibility: default -->
1685
<element name="Registers.dh">
1686
<short>DH register</short>
1689
<!-- variable Visibility: default -->
1690
<element name="Registers.eax">
1691
<short>EAX register</short>
1694
<!-- variable Visibility: default -->
1695
<element name="Registers.ebx">
1696
<short>EBX register</short>
1699
<!-- variable Visibility: default -->
1700
<element name="Registers.ecx">
1701
<short>ECX register</short>
1704
<!-- variable Visibility: default -->
1705
<element name="Registers.edx">
1706
<short>EDX register</short>
1709
<!-- variable Visibility: default -->
1710
<element name="Registers.ebp">
1711
<short>EBP register</short>
1714
<!-- variable Visibility: default -->
1715
<element name="Registers.esi">
1716
<short>ESI register</short>
1719
<!-- variable Visibility: default -->
1720
<element name="Registers.edi">
1721
<short>EDI register</short>
1724
<!-- variable Visibility: default -->
1725
<element name="TextRec.Handle">
1726
<short>File handle</short>
1729
<!-- variable Visibility: default -->
1730
<element name="TextRec.Mode">
1731
<short>File open mode</short>
1734
<!-- variable Visibility: default -->
1735
<element name="TextRec.bufsize">
1736
<short>Size of buffer</short>
1739
<!-- variable Visibility: default -->
1740
<element name="TextRec._private">
1741
<short>For internal use only</short>
1744
<!-- variable Visibility: default -->
1745
<element name="TextRec.bufpos">
1746
<short>buffer start position</short>
1749
<!-- variable Visibility: default -->
1750
<element name="TextRec.bufend">
1751
<short>buffer end position</short>
1754
<!-- variable Visibility: default -->
1755
<element name="TextRec.bufptr">
1756
<short>Pointer to buffer</short>
1759
<!-- variable Visibility: default -->
1760
<element name="TextRec.openfunc">
1761
<short>File open function</short>
1764
<!-- variable Visibility: default -->
1765
<element name="TextRec.inoutfunc">
1766
<short>File IO function</short>
1769
<!-- variable Visibility: default -->
1770
<element name="TextRec.flushfunc">
1771
<short>Data flush function</short>
1774
<!-- variable Visibility: default -->
1775
<element name="TextRec.closefunc">
1776
<short>File close function</short>
1779
<!-- variable Visibility: default -->
1780
<element name="TextRec.UserData">
1781
<short>User data (reserved)</short>
1784
<!-- variable Visibility: default -->
1785
<element name="TextRec.name">
1786
<short>File name</short>
1789
<!-- variable Visibility: default -->
1790
<element name="TextRec.LineEnd">
1791
<short>Line ending in use</short>
1794
<!-- variable Visibility: default -->
1795
<element name="TextRec.buffer">
1796
<short>Standard buffer</short>
1802
</fpdoc-descriptions>
b'\\ No newline at end of file'
added
removed
fpcdocs/dos.xml
