DOS

The [dos] section controls the emulated DOS environment itself - version number, memory management, and regional settings.

The reported DOS version defaults to 5.0, which covers the vast majority of games from the entire DOS era. A handful of very late titles check for DOS 7.0, and some very early ones expect DOS 3.0, but these are edge cases you'll likely never hit.

Memory management

The first IBM PCs only supported up to 640 KB of memory - the so-called "conventional memory" that DOS programs can access directly. As PCs gained more RAM, a patchwork of standards emerged to make the extra memory available:

• XMS (Extended Memory) - the main pool of memory above 1 MB. This is what the memsize setting controls (16 MB by default). Nearly all games from the late DOS era use XMS.

• EMS (Expanded Memory) - an older scheme that maps 64 KB pages of memory into the conventional memory area. Some early to mid-1990s games require EMS; a few older titles may actually malfunction if it's enabled.

• UMB (Upper Memory Blocks) - small pockets of memory between 640 KB and 1 MB, used to free up conventional memory by loading drivers and TSRs into them.

All three are enabled by default and you can safely ignore them. On the rare occasion a game misbehaves (usually an old title that chokes on EMS), disabling the offending memory type is a quick fix.

Regional settings

For language, country, keyboard layout, and code page settings, see the dedicated Localization chapter.

DOS version and compatibility

The ver setting controls which DOS version is reported to programs. The default 5.0 is the most widely compatible. Some older games require 3.3, while a few late-era programs need 6.22 or 7.1. Setting the DOS version to 7.0 or above automatically enables environment variable expansion in the DOS shell (see expand_shell_variable).

The setver_table_file setting provides persistent storage for the SETVER command, which lets you report a different DOS version to specific programs without changing the global version.

The file_locking setting emulates SHARE.EXE file locking. The default auto only enables it when Windows 3.1 is running, as it's required for some Windows 3.1 applications. In rare cases (e.g., Astral Blur demo), it can cause crashes in DOS games - set it to off if that happens.

Character devices

dosbox-automation implements the DOS character devices more completely than other DOSBox variants. The \DEV\ pseudo-directory resolves device names the way real DOS 2.0 and later does, so paths like \DEV\NUL work from any directory.

The CLOCK$ device, standard since DOS 2.0 but implemented in no other DOSBox variant, is fully functional: reading it returns the DOS date/time record, writing it sets the DOS date and time. TYPE \DEV\CLOCK$ prints one record and returns to the prompt. Programs that talk to the system clock through the device interface work as they would on real DOS.

Shell settings

The DOS shell supports persistent command history and environment variable expansion. The shell_history_file setting controls where the history is stored; set it to empty to disable persistence. The expand_shell_variable setting controls whether variables like %PATH% are expanded in commands - the default auto enables this for DOS 7.0+ (matching real FreeDOS and MS-DOS 7 behavior).

PCjr memory

The pcjr_memory_config setting controls memory layout on the emulated PCjr. The default expanded provides 640 KB and is compatible with most games. A few very old PCjr titles (Jumpman, Troll) require the standard 128 KB layout.

Interrupt stacks

The stacks setting replicates the STACKS=count,size directive that MS-DOS 3.2 introduced in CONFIG.SYS. It maintains a small private pool of stacks; whenever a hardware interrupt fires, dosbox-automation switches to a free slot before invoking the handler, then restores the original stack on the way out.

The default auto enables the feature on AT-class machine types, using the same defaults MS-DOS used - 9 stacks of 128 bytes each. It is disabled automatically on PC/XT-class machines (e.g., cga, pcjr, tandy), since this was the default under DOS. You will rarely need to change this; it exists for the edge case where a specific program misbehaves with interrupt stacks enabled, or needs a different stack count or size.

Configuration settings

You can set the DOS parameters in the [dos] configuration section.

Memory

ems

Enable EMS support. Enabled provides the best compatibility but certain applications may run better with other choices, or require EMS support to be disabled to work at all.

Possible values: on (default), off

xms

Enable XMS memory support.

Possible values: on (default), off

umb

Enable UMB memory support.

Possible values: on (default), off

pcjr_memory_config

Set PCjr memory layout.

Possible values:

Shell & version

ver

Set DOS version in MAJOR.MINOR format (5.0 by default). A single number is treated as the major version. Common settings are 3.3, 5.0, 6.22, and 7.1.

expand_shell_variable

Enable expanding environment variables such as %PATH% in the DOS command shell. FreeDOS and MS-DOS 7.0+ COMMAND.COM support this behavior.

Possible values:

file_locking

Enable file locking via emulating SHARE.EXE. This is required for some Windows 3.1 applications to work properly. It generally does not cause problems for DOS games except in rare cases (e.g., Astral Blur demo). If you experience crashes related to file permissions, you can try disabling this.

Possible values:

setver_table_file

File containing the list of applications and assigned DOS versions, in a tab-separated format, used by SETVER.EXE as a persistent storage (empty by default).

shell_history_file

File containing persistent command line history (shell_history.txt by default). Setting it to empty disables persistent shell history.

Interrupt stacks

stacks

Use DOS-style private stacks for hardware interrupts ('auto' by default). When a wrapped hardware interrupt fires, dosbox-automation switches to one stack from a private pool before invoking the previous handler. Disabling this means each running program must have enough stack space for hardware interrupts (and any chained handlers) itself. Most programs work correctly without it; a few legacy programs depend on it to avoid corrupting their own stack.

Note: the current implementation wraps the timer interrupt (INT 08h, IRQ0) and the keyboard interrupt (INT 09h, IRQ1). MS-DOS's STACKS feature wraps additional hardware-IRQ vectors; coverage may be expanded in future versions.

Possible values: