21 System Calls Reference
34 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
36 | C A V E A T P R O G R A M M E R |
38 | Certain structures, constants and system calls below |
39 | are private to the DOS and are extremely |
40 | version-dependent. They may change at any time at the |
41 | implementors' whim. As a result, they must not be |
42 | documented to the general public. If an extreme case |
43 | arises, they must be documented with this warning. |
45 | Those structures and constants that are subject to the |
46 | above will be marked and bracketed with the flag: |
48 | C A V E A T P R O G R A M M E R |
50 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
71 Extensions to existing call structure
74 Name: * Alloc - allocate memory
80 ; AX:0 is pointer to allocated memory
81 ; if alloc fails, BX is the largest block available
84 Alloc returns a pointer to a free block of memory
85 that has the requested size in paragraphs.
88 AX = error_not_enough_memory
89 The largest available free block is smaller
90 than that requested or there is no free block.
92 The internal consistency of the memory arena
93 has been destroyed. This is due to a user
94 program changing memory that does not belong
98 Name: * CharOper - change incompatible configuration
106 ; on read functions, data is returned in DL
109 CharOper allows a program to change system
110 parameters to allow for switch indicators and whether
111 devices are available at every level of the directory
114 A function code is passed in AL:
118 0 DL, on return, will contain the DOS switch
119 character. On most systems this will default to
121 1 Set the switch character to the character in DL.
122 2 Read the device availability byte into DL. If
123 this byte is 0, then devices must be accessed in
124 file I/O calls by /dev/device. If this byte is
125 non-zero, then the devices are available at every
126 node of the directory tree (i.e. CON is the
127 console device not the file CON). This byte is
129 3 Set the device availability byte to the value in
134 The function code specified in AL is not in
138 Name: * CurrentDir - return text of current directory
145 ; DS:SI is a pointer to 64 byte area that contains
146 ; drive current directory.
149 CurrentDir returns the current directory for a
150 particular drive. The directory is root-relative and
151 does not contain the drive specifier. The drive code
152 passed in DL is 0=default, 1=A, 2=B, etc.
155 AX = error_invalid_drive
156 The drive specified in DL was invalid.
159 Name: * Dealloc - free allocated memory
167 Dealloc returns a piece of memory to the system
168 pool that was allocated by alloc.
171 AX = error_invalid_block
172 The block passed in ES is not one allocated
174 = error_arena_trashed
175 The internal consistency of the memory arena
176 has been destroyed. This is due to a user
177 program changing memory that does not belong
181 Name: * FileTimes - get/set the write times of a
188 ; if AL = 1 then then next two are mandatory
192 ; if AL = 0 then CX/DX has the last write time/date
196 FileTimes returns or sets the last-write time for
197 a handle. These times are not recorded until the file
200 A function code is passed in AL:
204 0 Return the time/date of the handle in CX/DX
205 1 Set the time/date of the handle to CX/DX
208 AX = error_invalid_function
209 The function passed in AL was not in the range
211 = error_invalid_handle
212 The handle passed in BX was not currently
216 Name: * FindFirst - find matching file
223 ; DMA address has datablock
226 FindFirst takes a pathname with wildcards in the
227 last component (passed in DS:DX), a set of attributes
228 (passed in CX) and attempts to find all files that
229 match the pathname and have a subset of the required
230 attributes. A datablock at the current DMA is written
231 that contains information in the following form:
234 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
235 | C A V E A T P R O G R A M M E R |
237 find_buf_sattr DB ? ; attribute of search
238 find_buf_drive DB ? ; drive of search
239 find_buf_name DB 11 DUP (?); search name
240 find_buf_LastEnt DW ? ; LastEnt
241 find_buf_ThisDPB DD ? ; This DPB
242 find_buf_DirStart DW ? ; DirStart
244 | C A V E A T P R O G R A M M E R |
245 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
247 find_buf_attr DB ? ; attribute found
248 find_buf_time DW ? ; time
249 find_buf_date DW ? ; date
250 find_buf_size_l DW ? ; low(size)
251 find_buf_size_h DW ? ; high(size)
252 find_buf_pname DB 13 DUP (?) ; packed name
255 To obtain the subsequent matches of the pathname,
256 see the description of FindNext
259 AX = error_file_not_found
260 The path specified in DS:DX was an invalid
262 = error_no_more_files
263 There were no files matching this
267 Name: * FindNext - step through a directory matching
271 ; DMA points at area returned by find_first
274 ; next entry is at dma
277 FindNext finds the next matching entry in a
278 directory. The current DMA address must point at a
279 block returned by FindFirst (see FindFirst).
282 AX = error_no_more_files
283 There are no more files matching this pattern.
286 Name: * GetDMA - get current DMA transfer address
291 ; ES:BX has current DMA transfer address
294 Return DMA transfer address.
299 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
300 | C A V E A T P R O G R A M M E R |
303 Name: * GetDSKPT(DL) - get pointer to drive parameter
309 ; DS:BX has address of drive parameter block
312 Return pointer to default drive parameter block.
321 ; DS:BX has address of drive parameter block
324 Return pointer to drive parameter block for drive
325 designated in DL (0=Default, A=1, B=2 ...)
329 The drive given in DL is invalid.
331 | C A V E A T P R O G R A M M E R |
332 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
335 Name: * GetFreespace - get Disk free space
339 MOV DL,Drive ;0 = default, A = 1
341 ; BX = Number of free allocation units on drive
342 ; DX = Total number of allocation units on drive
343 ; CX = Bytes per sector
344 ; AX = Sectors per allocation unit
347 Return Free space on disk along with additional
348 information about the disk.
352 The drive number given in DL was invalid.
354 NOTE: This call returns the same information in the same
355 registers (except for the FAT pointer) as the get FAT
356 pointer calls did in previous versions of the DOS.
359 Name: * GetInDOSF - get DOS critical-section flag
364 ; ES:BX has location of the flag
369 MOV AX, DWORD PTR Crit
376 Return location of indos flag. On return ES:BX is
377 the address of a byte memory cell inside the DOS. If
378 used in an interrupt service routine, it indicates
379 whether or not the DOS was interrupted in a critical
380 section. If the cell was zero, then the DOS was not
381 in a critical section and thus can be called by the
382 interrupt routine. If the cell was non-zero, the DOS
383 should be considered to be in an uninterruptable state
384 and for reliability, no DOS calls should be given.
390 Name: * GetVector - get interrupt vector
396 ; ES:BX now has long pointer to interrupt routine
399 Return interrupt vector associated with an
406 Name: * GetVerifyFlag - return current setting of the
407 verify after write flag.
412 ; AL is the current verify flag value
415 The current value of the verify flag is returned
422 Name: * GetVersion - get DOS version number
427 ; AL is the major version number
428 ; AH is the minor version number
429 ; BH is the OEM number
430 ; BL:CX is the (24 bit) user number
433 Return MS-DOS version number. On return AL.AH
434 will be the two part version designation, ie. for
435 MS-DOS 1.28 AL would be 1 and AH would be 28. For pre
436 1.28 DOS AL = 0. Note that version 1.1 is the same as
437 1.10, not the same as 1.01.
443 Name: * International - return country dependent
448 MOV AH, International
453 This call returns in the block of memory pointed
454 to by DS:DX, the following information pertinent to
455 international applications:
457 +---------------------------+
458 | WORD Date/time format |
459 +---------------------------+
460 | BYTE ASCIZ string |
462 +---------------------------+
463 | BYTE ASCIZ string |
464 | thousands separator |
465 +---------------------------+
466 | BYTE ASCIZ string decimal |
468 +---------------------------+
470 The date/time format has the following values and
473 0 - USA standard h:m:s m/d/y
474 1 - Europe standard h:m:s d/m/y
475 2 - Japan standard y/m/d h:m:s
477 The value passed in AL is either 0 (for current
478 country) or a country code (to be defined later.
479 Currently the country code must be zero).
482 AX = error_invalid_function
483 The function passed in AL was not 0
487 Name: * KeepProcess - terminate process and remain
497 This call terminates the current process and
498 attempts to set the initial allocation block to a
499 specific size in paragraphs. It will not free up any
500 other allocation blocks belonging to that process.
501 The exit code passed in AX is retrievable by the
508 Name: * Rename - move a directory entry
517 Rename will attempt to rename a file into another
518 path. The paths must be on the same device.
521 AX = error_file_not_found
522 The file name specifed by DS:DX was not found.
523 = error_not_same_device
524 The source and destination are on different
526 = error_access_denied
527 The path specified in DS:DX was a directory or
528 the file specified by ES:DI exists or the
529 destination directory entry could not be
533 Name: * SetBlock - modify allocated blocks
540 ; if setblock fails for growing, BX will have the
541 ; maximum size possible
544 Setblock will attempt to grow/shrink an allocated
548 AX = error_invalid_block
549 The block passed in ES is not one allocated
551 = error_arena_trashed
552 The internal consistency of the memory arena
553 has been destroyed. This is due to a user
554 program changing memory that does not belong
556 = error_not_enough_memory
557 There was not enough free memory after the
558 specified block to satisfy the grow request.
561 Name: * SetCtrlCTrapping - turn on/off broad ^C
566 MOV AH,SetCtrlCTrapping
569 ; If AL was 0, then DL has the current value of the
573 MSDOS ordinarily checks for a ^C on the
574 controlling device only when doing a function 1-12
575 operation to that device. SetCtrlCTrapping allows the
576 user to expand this checking to include any system
577 call. For example, with the ^C trapping off, all disk
578 I/O will proceed without interruption while with ^C
579 trapping on, the ^C interrupt is given at the system
580 call that initiates the disk operation.
584 The function passed in AL was not in the range
587 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
588 | C A V E A T P R O G R A M M E R |
591 Name: * Set_OEM_Handler - set handler for OEM
592 specific INT 21H calls.
595 LDS DX,handler_address
596 MOV AH,Set_OEM_Handler
600 Set handler address for 0F9H-0FFH INT 21H system
601 calls to DS:DX. To return the 0F9H-0FFH calls to
602 the uninitialized state, give DS=DX=-1.
608 All registers as user set them when INT 21H
609 issued (including SS:SP). INT 21 return is on
610 stack, so the correct method for the OEM handler
611 to return to the user is to give an IRET. The
612 OEM handler is free to make any INT 21H system
613 call (including the 0F9H- 0FFH group if the OEM
614 handler is re-entrant).
617 The AH INT 21H function codes 0F8H through 0FFH are
618 reserved for OEM extensions to the INT 21H calling
619 convention. These calls have two states, initialized
620 and uninitialized. There will be one handler for all 7
621 (0F9-0FFH) functions. When the DOS is first
622 initialized, these calls are uninitialized. The AH=0F8H
623 call is the call which will set the handler address for
624 the 0F9-0FFH calls. If the 0F9-0FFH calls are
625 uninitialized, an attempt to call them results in the
626 normal invalid system call number return.
627 OEMs should NOT document the 0F8 call.
629 | C A V E A T P R O G R A M M E R |
630 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
651 XENIX-compatible system calls
655 Previous to version 2.0, MSDOS had a simple single
656 directory structure that sufficed for small (160k to 320K)
657 diskettes. As the need for hard disk support grows, and
658 as MSDOS 2.0 will support a wide variety of hard disks,
659 the need for better disk organization also grows. Merely
660 expanding the directory is not an effective solution;
661 doing a 'DIR' on a directory with 1000 files is not a
662 user-friendly characteristic.
664 People, by nature, think in hierarchical terms:
665 organization charts and family trees, for example. It
666 would be nice to allow users to organize their files on
667 disk in a similar manner. Consider the following:
669 In a particular business, both sales and accounting
670 share a computer with a large disk and the individual
671 employees use it for preparation of reports and
672 maintaining accounting information. One would naturally
673 view the organization of files on the disk in this
688 report accts. report accts. report report
691 In MSDOS 2.0 the user can arrange his files in such a
692 manner that files that are not part of his current task do
693 not interfere with that task. Pre-2.0 versions of MSDOS
694 has a single directory that contains files. MSDOS extends
695 this concept to allow a directory to contain both files
696 and directories and to introduce the notion of the
699 To specify a filename, the user could use one of two
700 methods, either specify a path from the root node to the
701 file, or specify a path from the current node to the file.
702 A path is a series of directory names separated by '/' and
703 ending with a filename. A path that starts at the root
706 There is a special directory entry in each directory,
707 denoted by '..' that is the parent of the directory. The
708 root directory's parent is itself (who created God?).
710 Using a directory structure like the hierarchy above,
711 and assuming that the current directory is at point (D),
712 to reference the report under John, the following are all
719 To refer to the report under Mary, the following are
725 To refer to the report under Sue, the following are
728 ../../accounting/Sue/report
729 /accounting/Sue/report
731 There is no restriction in MSDOS 2.0 on the depth of a
732 tree (the length of the longest path from root to leaf)
733 except in the number of allocation units available. The
734 root directory will have a fixed number of entries, 64 for
735 the single sided diskettes to XXX for a large hard disk.
736 For non-root directories, there is no limit to the number
737 of files per directory excepting in the number of
738 allocation units available.
740 Old (pre-2.0) disks will appear to MSDOS 2.0 as having
741 only a root directory with files in it and no
742 subdirectories whatever.
744 Implementation of the tree-structure is simple. The
745 root directory is the pre-2.0 directory. Subdirectories
746 of the root have a special attribute set indicating that
747 they are directories. The subdirectories themselves are
748 files, linked through the FAT as usual. Their contents
749 are identical in character to the contents of the root
752 Pre-2.0 programs that use system calls not described
753 below will not be able to make use of files in other
754 directories. They will only be able to access files in
755 the current directory. This is no great loss of
756 functionality as users will aggregate their files into
757 sub-directories on basis of functionality; the files that
758 are being used will be found in the current directory.
759 Those that are not necessary for the current task will be
760 placed in other directories. Out of sight, out of mind.
762 There are also new attributes in 2.0. These and the
763 old attributes apply to the tree structured directories in
764 the following manner:
766 Attribute Meaning/Function Meaning/Function
767 for files for directories
769 volume_id Present at the root. Meaningless.
770 Only one file may have
773 directory Meaningless. Indicates that the
778 read_only Old fcb-create, new Meaningless.
783 archive Set when file is Meaningless.
784 written. Set/reset via
787 hidden/ Prevents file from Prevents directory
788 system being found in search entry from being
789 first/search next. found. ChDir to
790 New open will fail. directory will still
794 Name: * ChDir - Change the current directory
802 ChDir is given the ASCIZ name of the directory
803 which is to become the current directory. If any
804 member of the specified pathname does not exist, then
805 the current directory is unchanged. Otherwise, the
806 current directory is set to the string.
809 AX = error_path_not_found
810 The path specified in DS:DX either indicated a
811 file or the path was invalid.
814 Name: * ChMod - change write protection
824 Given an ASCIZ name, ChMod will set/get the
825 attributes of the file to those given in CX.
827 A function code is passed in AL:
831 0 Return the attributes of the file in CX
832 1 Set the attributes of the file to those in CX
835 AX = error_path_not_found
836 The path specified was invalid.
837 = error_access_denied
838 The attributes specified in CX contained one
839 that could not be changed (directory, volume
841 = error_invalid_function
842 The function passed in AL was not in the range
846 Name: * Close - close a file handle
854 In BX is passed a file handle (like that returned
855 by Open, Creat or Dup); the Close call will close the
856 associated file. Internal buffers are flushed.
859 AX = error_invalid_handle
860 The handle passed in BX was not currently
864 Name: * Creat - create a file
871 ; AX now has the handle
874 Creat creates a new file or truncates an old file
875 to zero length in preparation for writing. If the
876 file did not exist, then the file is created in the
877 appropriate directory and the file is given the
878 read/write protection code of access.
880 CX contains the default attributes to be set for
881 the file. Currently, the read-only bit must be off.
884 AX = error_access_denied
885 The attributes specified in CX contained one
886 that could not be created (directory, volume
887 ID), a file already existed with a more
888 inclusive set of attributes, or a directory
889 existed with the same name.
890 = error_path_not_found
891 The path specified was invalid.
892 = error_too_many_open_files
893 The file was created with the specified
894 attributes, but there were no free handles
895 available for the process or that the internal
896 system tables were full.
899 Name: * Dup - duplicate a file handle
905 ; AX has the returned handle
908 Dup takes an already opened file handle and
909 returns a new handle that refers to the same file at
913 AX = error_invalid_handle
914 The handle passed in BX was not currently
916 = error_too_many_open_files
917 There were no free handles available in the
918 current process or the internal system tables
922 Name: * Dup2 - force a duplicate of a handle
931 Dup2 will cause newfh to refer to the same stream
932 as fh. If there was an open file on newfh, then it is
936 AX = error_invalid_handle
937 The handle passed in BX was not currently
941 Name: * Exec - load / execute a program
951 This call allows a program to load another program
952 into memory and (default) begin execution of it.
953 DS:DX points to the ASCIZ name of the file to be
954 loaded. ES:BX points to a parameter block for the
957 A function code is passed in AL:
961 0 Load and execute the program. A program header is
962 established for the program and the terminate and
963 ^C addresses are set to the instruction after the
966 NOTE: When control is returned, via a ^C or
967 terminate, from the program being EXECed ALL
968 registers are altered including the stack.
969 This is because control is returned from the
970 EXECed program, not the system. To regain
971 your stack, store an SS:SP value in a data
972 location reachable from your CS.
974 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
975 | C A V E A T P R O G R A M M E R |
977 1 Load, create the program header but do not begin
978 execution. The CS:IP/SS:SP of the program are
979 returned in the area provided by the user.
981 | C A V E A T P R O G R A M M E R |
982 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
984 3 Load, do not create the program header, and do not
985 begin execution. This is useful in loading
988 For each value of AL, the block has the following
991 AL = 0 -> load/execute program
993 +---------------------------+
994 | WORD segment address of |
996 +---------------------------+
997 | DWORD pointer to command |
999 +---------------------------+
1000 | DWORD pointer to default |
1001 | FCB to be passed at 5Ch |
1002 +---------------------------+
1003 | DWORD pointer to default |
1004 | FCB to be passed at 6Ch |
1005 +---------------------------+
1007 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
1008 | C A V E A T P R O G R A M M E R |
1010 AL = 1 -> load program
1012 +---------------------------+
1013 | WORD segment address of |
1015 +---------------------------+
1016 | DWORD pointer to command |
1018 +---------------------------+
1019 | DWORD pointer to default |
1020 | FCB to be passed at 5Ch |
1021 +---------------------------+
1022 | DWORD pointer to default |
1023 | FCB to be passed at 6Ch |
1024 +---------------------------+
1025 | DWORD returned value of |
1027 +---------------------------+
1028 | DWORD returned value of |
1030 +---------------------------+
1032 | C A V E A T P R O G R A M M E R |
1033 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
1035 AL = 3 -> load overlay
1037 +---------------------------+
1038 | WORD segment address where|
1039 | file will be loaded. |
1040 +---------------------------+
1041 | WORD relocation factor to |
1042 | be applied to the image. |
1043 +---------------------------+
1045 Note that all open files of a process are
1046 duplicated in the child process after an Exec. This
1047 is extremely powerful; the parent process has control
1048 over the meanings of stdin, stdout, stderr, stdaux and
1049 stdprn. The parent could, for example, write a series
1050 of records to a file, open the file as standard input,
1051 open a listing file as standard output and then Exec a
1052 sort program that takes its input from stdin and
1055 Also inherited (or passed from the parent) is an
1056 'environment'. This is a block of text strings (less
1057 than 32K bytes total) that convey various
1058 configurations parameters. The format of the
1059 environment is as follows:
1061 (paragraph boundary)
1062 +---------------------------+
1063 | BYTE asciz string 1 |
1064 +---------------------------+
1065 | BYTE asciz string 2 |
1066 +---------------------------+
1068 +---------------------------+
1069 | BYTE asciz string n |
1070 +---------------------------+
1072 +---------------------------+
1074 Typically the environment strings have the form:
1078 for example, COMMAND.COM always passes its execution
1081 PATH=A:/BIN;B:/BASIC/LIB
1083 A zero value of the environment address will cause the
1084 child process to inherit the parent's environment
1087 Note that on a successful return from EXEC, all
1088 registers, except for CS:IP, are changed.
1091 AX = error_invalid_function
1092 The function passed in AL was not 0, 1 or 3.
1093 = error_bad_environment
1094 The environment was larger than 32Kb.
1096 The file pointed to by DS:DX was an EXE format
1097 file and contained information that was
1098 internally inconsistent.
1099 = error_not_enough_memory
1100 There was not enough memory for the process to
1102 = error_file_not_found
1103 The path specified was invalid or not found.
1106 Name: * Exit - terminate a process
1114 Exit will terminate the current process,
1115 transferring control to the invoking process. In
1116 addition, a return code may be sent. All files open
1117 at the time are closed.
1123 Name: * Ioctl - I/O control for devices
1128 (or MOV BL, drive for calls AL=4,5
1134 MOV CX, count for calls AL=2,3,4,5)
1139 ; For calls AL=2,3,4,5 AX is the number of bytes
1140 ; transferred (same as READ and WRITE).
1141 ; For calls AL=6,7 AL is status returned, AL=0 if
1142 ; status is not ready, AL=0FFH otherwise.
1145 Set or Get device information associated with open
1146 Handle, or send/receive control string to device
1149 The following values are allowed for func:
1153 0 Get device information (returned in DX)
1154 1 Set device information (as determined by DX)
1155 2 Read CX number of bytes into DS:DX from device
1157 3 Write CX number of bytes from DS:DX to device
1159 4 Same as 2 only drive number in BL
1160 0=default,A=1,B=2,...
1161 5 Same as 3 only drive number in BL
1162 0=default,A=1,B=2,...
1166 Ioctl can be used to get information about device
1167 channels. It is ok to make Ioctl calls on regular
1168 files but only calls 0,6 and 7 are defined in that
1169 case (AL=0,6,7), all other calls return an
1170 error_invalid_function error.
1174 The bits of DX are defined as follows for calls
1175 AL=0 and AL=1. Note that the upper byte MUST be zero
1179 15 14 13 12 11 10 9 8|7 6 5 4 3 2 1 0
1180 +--+--+--+--+--+--+-+-+-+-+-+-+-+-+-+-+
1181 | R| C| |I|E|R|S|I|I|I|I|
1182 | e| T| |S|O|A|P|S|S|S|S|
1183 | s| R| Reserved |D|F|W|E|C|N|C|C|
1184 | | L| |E| | |C|L|U|O|I|
1185 | | | |V| | |L|K|L|T|N|
1186 +--+--+--+--+--+--+-+-+-+-+-+-+-+-+-+-+
1189 ISDEV = 1 if this channel is a device
1190 = 0 if this channel is a disk file (Bits 8-15 =
1195 EOF = 0 if End Of File on input
1196 RAW = 1 if this device is in Raw mode
1197 = 0 if this device is cooked
1198 ISCLK = 1 if this device is the clock device
1199 ISNUL = 1 if this device is the null device
1200 ISCOT = 1 if this device is the console output
1201 ISCIN = 1 if this device is the console input
1202 SPECL = 1 if this device is special
1204 CTRL = 0 if this device can NOT do control strings
1205 via calls AL=2 and AL=3.
1206 CTRL = 1 if this device can process control
1207 strings via calls AL=2 and AL=3.
1208 NOTE that this bit cannot be set.
1211 EOF = 0 if channel has been written
1212 Bits 0-5 are the block device number for the
1213 channel (0 = A, 1 = B, ...)
1215 Bits 15,8-13,4 are reserved and should not be altered.
1218 These four calls allow arbitrary control strings to be
1219 sent or received from a device. The Call syntax is
1220 the same as the READ and WRITE calls, except for 4 and
1221 5 which take a drive number in BL instead of a handle
1224 An error_invalid_function error is returned if the
1225 CTRL bit (see above) is 0.
1227 An error_access_denied is returned by calls AL=4,5 if
1228 the drive number is invalid.
1231 These two calls allow the user to check if a file
1232 handle is ready for input or output. Status of
1233 handles open to a device is the intended use of these
1234 calls, but status of a handle open to a disk file is
1235 OK and is defined as follows:
1238 Always ready (AL=FF) until EOF reached, then
1239 always not ready (AL=0) unless current
1240 position changed via LSEEK.
1242 Always ready (even if disk full).
1245 The status is defined at the time the system is
1246 CALLED. On future versions, by the time control is
1247 returned to the user from the system, the status
1248 returned may NOT correctly reflect the true current
1249 state of the device or file.
1252 AX = error_invalid_handle
1253 The handle passed in BX was not currently
1255 = error_invalid_function
1256 The function passed in AL was not in the range
1258 = error_invalid_data
1259 = error_access_denied (calls AL=4..7)
1262 Name: * LSeek - move file read/write pointer
1271 ; DX:AX has the new location of the pointer
1274 LSeek moves the read/write pointer according to
1279 0 The pointer is moved to offset bytes from the
1280 beginning of the file.
1281 1 The pointer is moved to the current location
1283 2 The pointer is moved to the end of file plus
1286 Offset should be regarded as a 32-bit integer with
1287 CX occupying the most significant 16 bits.
1290 AX = error_invalid_handle
1291 The handle passed in BX was not currently
1293 = error_invalid_function
1294 The function passed in AL was not in the range
1298 Name: * MkDir - Create a directory entry
1306 Given a pointer to an ASCIZ name, create a new
1307 directory entry at the end.
1310 AX = error_path_not_found
1311 The path specified was invalid or not found.
1312 = error_access_denied
1313 The directory could not be created (no room in
1314 parent directory), the directory/file already
1315 existed or a device name was specified.
1318 Name: * Open - access a file
1325 ; AX has error or file handle
1326 ; If successful open
1329 Open associates a 16-bit file handle with a file.
1331 The following values are allowed for access:
1335 0 file is opened for reading
1336 1 file is opened for writing
1337 2 file is opened for both reading and writing.
1339 DS:DX point to an ASCIZ name of the file to be
1342 The read/write pointer is set at the first byte of
1343 the file and the record size of the file is 1 byte.
1344 The returned file handle must be used for subsequent
1347 The DOS, on initialization, will have a maximum
1348 number of files. See the configuration file document
1349 for information on changing this default.
1352 AX = error_invalid_access
1353 The access specified in AL was not in the
1355 = error_file_not_found
1356 The path specified was invalid or not found.
1357 = error_access_denied
1358 The user attempted to open a directory or
1359 volume-id, or open a read-only file for
1361 = error_too_many_open_files
1362 There were no free handles available in the
1363 current process or the internal system tables
1367 Name: * Read - Do file/device I/O
1375 ; AX has number of bytes read
1378 Read transfers count bytes from a file into a
1379 buffer location. It is not guaranteed that all count
1380 bytes will be read; for example, reading from the
1381 keyboard will read at most one line of text. If the
1382 returned value is zero, then the program has tried to
1383 read from the end of file.
1385 All I/O is done using normalized pointers; no
1386 segment wraparound will occur.
1389 AX = error_invalid_handle
1390 The handle passed in BX was not currently
1392 = error_access_denied
1393 The handle passed in BX was opened in a mode
1394 that did not allow reading.
1397 Name: * RmDir - Remove a directory entry
1405 RmDir is given an asciz name of a directory. That
1406 directory is removed from its parent
1409 AX = error_path_not_found
1410 The path specified was invalid or not found.
1411 = error_access_denied
1412 The path specified was not empty, not a
1413 directory, the root directory or contained
1414 invalid information.
1415 = error_current_directory
1416 The path specified was the current directory
1420 Name: * Unlink - delete a directory entry
1428 Unlink removes a directory entry associated with a
1429 filename. If the file is currently open on another
1430 handle, then no removal will take place.
1433 AX = error_file_not_found
1434 The path specified was invalid or not found.
1435 = error_access_denied
1436 The path specified was a directory or
1440 Name: * Wait - retrieve the return code of a child
1445 ; AX has the exit code
1448 Wait will return the Exit code specified by a
1449 child process. It will return this Exit code only
1450 once. The low byte of this code is that sent by the
1451 Exit routine. The high byte is one of the following:
1456 3 - Terminate and stay resident
1462 Name: * Write - write to a file
1470 ; AX has number of bytes written
1473 Write transfers count bytes from a buffer into
1474 a file. It should be regarded as an error if the
1475 number of bytes written is not the same as the number
1478 It is important to note that the write system
1479 call with a count of zero (CX = 0) will truncate
1480 the file at the current position.
1482 All I/O is done using normalized pointers; no
1483 segment wraparound will occur.
1486 AX = error_invalid_handle
1487 The handle passed in BX was not currently
1489 = error_access_denied
1490 The handle was not opened in a mode that
1494 The following XENIX convention is followed for the new 2.0
1497 o If no error occurred, then the carry flag will be
1498 reset and register AX will contain the appropriate
1501 o If an error occurred, then the carry flag will be
1502 set and register AX will contain the error code.
1504 The following code sample illustrates the recommended method
1505 of detecting these errors:
1515 The word variable errno will now have the correct error code
1516 for that system call.
1518 The current equates for the error codes are:
1520 no_error_occurred EQU 0
1522 error_invalid_function EQU 1
1523 error_file_not_found EQU 2
1524 error_path_not_found EQU 3
1525 error_too_many_open_files EQU 4
1526 error_access_denied EQU 5
1527 error_invalid_handle EQU 6
1528 error_arena_trashed EQU 7
1529 error_not_enough_memory EQU 8
1530 error_invalid_block EQU 9
1531 error_bad_environment EQU 10
1532 error_bad_format EQU 11
1533 error_invalid_access EQU 12
1534 error_invalid_data EQU 13
1535 error_invalid_drive EQU 15
1536 error_current_directory EQU 16
1537 error_not_same_device EQU 17
1538 error_no_more_files EQU 18
1541 System call assignments:
1544 STD_CON_INPUT EQU 1 ; 1 1
1545 STD_CON_OUTPUT EQU 2 ; 2 2
1546 STD_AUX_INPUT EQU 3 ; 3 3
1547 STD_AUX_OUTPUT EQU 4 ; 4 4
1548 STD_PRINTER_OUTPUT EQU 5 ; 5 5
1549 RAW_CON_IO EQU 6 ; 6 6
1550 RAW_CON_INPUT EQU 7 ; 7 7
1551 STD_CON_INPUT_NO_ECHO EQU 8 ; 8 8
1552 STD_CON_STRING_OUTPUT EQU 9 ; 9 9
1553 STD_CON_STRING_INPUT EQU 10 ; 10 A
1554 STD_CON_INPUT_STATUS EQU 11 ; 11 B
1555 STD_CON_INPUT_FLUSH EQU 12 ; 12 C
1556 DISK_RESET EQU 13 ; 13 D
1557 SET_DEFAULT_DRIVE EQU 14 ; 14 E
1558 FCB_OPEN EQU 15 ; 15 F
1559 FCB_CLOSE EQU 16 ; 16 10
1560 DIR_SEARCH_FIRST EQU 17 ; 17 11
1561 DIR_SEARCH_NEXT EQU 18 ; 18 12
1562 FCB_DELETE EQU 19 ; 19 13
1563 FCB_SEQ_READ EQU 20 ; 20 14
1564 FCB_SEQ_WRITE EQU 21 ; 21 15
1565 FCB_CREATE EQU 22 ; 22 16
1566 FCB_RENAME EQU 23 ; 23 17
1567 GET_DEFAULT_DRIVE EQU 25 ; 25 19
1568 SET_DMA EQU 26 ; 26 1A
1569 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
1570 | C A V E A T P R O G R A M M E R |
1572 GET_DEFAULT_DPB EQU 31 ; 31 1F
1574 | C A V E A T P R O G R A M M E R |
1575 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
1576 FCB_RANDOM_READ EQU 33 ; 33 21
1577 FCB_RANDOM_WRITE EQU 34 ; 34 22
1578 GET_FCB_FILE_LENGTH EQU 35 ; 35 23
1579 GET_FCB_POSITION EQU 36 ; 36 24
1580 SET_INTERRUPT_VECTOR EQU 37 ; 37 25
1581 CREATE_PROCESS_DATA_BLOCK EQU 38 ; 38 26
1582 FCB_RANDOM_READ_BLOCK EQU 39 ; 39 27
1583 FCB_RANDOM_WRITE_BLOCK EQU 40 ; 40 28
1584 PARSE_FILE_DESCRIPTOR EQU 41 ; 41 29
1585 GET_DATE EQU 42 ; 42 2A
1586 SET_DATE EQU 43 ; 43 2B
1587 GET_TIME EQU 44 ; 44 2C
1588 SET_TIME EQU 45 ; 45 2D
1589 SET_VERIFY_ON_WRITE EQU 46 ; 46 2E
1590 ; Extended functionality group
1591 GET_DMA EQU 47 ; 47 2F
1592 GET_VERSION EQU 48 ; 48 30
1593 KEEP_PROCESS EQU 49 ; 49 31
1594 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
1595 | C A V E A T P R O G R A M M E R |
1597 GET_DPB EQU 50 ; 50 32
1599 | C A V E A T P R O G R A M M E R |
1600 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
1601 SET_CTRL_C_TRAPPING EQU 51 ; 51 33
1602 GET_INDOS_FLAG EQU 52 ; 52 34
1603 GET_INTERRUPT_VECTOR EQU 53 ; 53 35
1604 GET_DRIVE_FREESPACE EQU 54 ; 54 36
1605 CHAR_OPER EQU 55 ; 55 37
1606 INTERNATIONAL EQU 56 ; 56 38
1609 MKDIR EQU 57 ; 57 39
1610 RMDIR EQU 58 ; 58 3A
1611 CHDIR EQU 59 ; 59 3B
1613 CREAT EQU 60 ; 60 3C
1615 CLOSE EQU 62 ; 62 3E
1617 WRITE EQU 64 ; 64 40
1618 UNLINK EQU 65 ; 65 41
1619 LSEEK EQU 66 ; 66 42
1620 CHMOD EQU 67 ; 67 43
1621 IOCTL EQU 68 ; 68 44
1623 XDUP2 EQU 70 ; 70 46
1624 CURRENT_DIR EQU 71 ; 71 47
1626 ALLOC EQU 72 ; 72 48
1627 DEALLOC EQU 73 ; 73 49
1628 SETBLOCK EQU 74 ; 74 4A
1633 FIND_FIRST EQU 78 ; 78 4E
1635 FIND_NEXT EQU 79 ; 79 4F
1636 ; SPECIAL SYSTEM GROUP
1637 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
1638 | C A V E A T P R O G R A M M E R |
1640 SET_CURRENT_PDB EQU 80 ; 80 50
1641 GET_CURRENT_PDB EQU 81 ; 81 51
1642 GET_IN_VARS EQU 82 ; 82 52
1643 SETDPB EQU 83 ; 83 53
1645 | C A V E A T P R O G R A M M E R |
1646 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
1647 GET_VERIFY_ON_WRITE EQU 84 ; 84 54
1648 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
1649 | C A V E A T P R O G R A M M E R |
1651 DUP_PDB EQU 85 ; 85 55
1653 | C A V E A T P R O G R A M M E R |
1654 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
1655 RENAME EQU 86 ; 86 56
1656 FILE_TIMES EQU 87 ; 87 57
projects / MS-DOS.git / blob