NAME

dosbox - DOSBox Staging, x86/DOS emulator, a modern continuation of DOSBox

SYNOPSIS

dosbox [--fullscreen] [--startmapper] [--noautoexec] [--securemode] [--conf <configfile>] [--lang <langfile>] [--machine <type>] [--socket <num>] [-c <command>] [--exit] [PATH]

dosbox --help

dosbox --version

dosbox --printconf

dosbox --editconf

dosbox --eraseconf

dosbox --noprimaryconf

dosbox --nolocalconf

dosbox --set <property>=<value>

dosbox --working-dir <path>

dosbox --list-countries

dosbox --list-glshaders

dosbox --erasemapper

DESCRIPTION

This manual page briefly documents DOSBox Staging, a modern continuation of DOSBox.

If PATH is a directory, it's mounted as C:.
If PATH is a bootable disk image (.IMA/.IMG), it's booted.
If PATH is a CD-ROM disc image (.CUE/.ISO), it's mounted as D:.
If PATH is a DOS executable (.BAT/.COM/.EXE), it's parent path is mounted as C: and the executable is run. When the executable exits, DOSBox Staging quits.

For an introduction, type INTRO inside DOSBox Staging.

The document will refer to DOSBox Staging as dosbox from now on for readability.

OPTIONS

Legacy single dash abbrevations still work for backwards compatibility.

--conf <config_file> Start with the options specified in <config_file>.
Multiple configuration files can be specified.
Example: --conf conf1.conf --conf conf2.conf

--printconf Print the location of the primary configuration file.

--editconf Open the primary configuration file in a text editor.

--eraseconf Delete the primary configuration file.

--noprimaryconf Don't load or create the primary configuration file.

--nolocalconf Don't load the local 'dosbox.conf' configuration file
if present in the current working directory.

--set <setting>=<value> Set a configuration setting. Multiple configuration
settings can be specified. Example:
--set mididevice=fluidsynth --set soundfont=mysoundfont.sf2

--working-dir <path> Set working directory to <path>. DOSBox will act as if
started from this directory.

--list-countries List all supported countries with their numeric codes.
Codes are to be used in the 'country' config setting.

--list-glshaders List all available OpenGL shaders and their paths.
Shaders are to be used in the 'glshader' config setting.

--fullscreen Start in fullscreen mode.

--lang <lang_file> Start with the language specified in <lang_file>.

--machine <type> Emulate a specific type of machine. The machine type has
influence on both the emulated video and sound cards.
Valid choices are: hercules, cga, cga_mono, tandy,
pcjr, ega, svga_s3 (default), svga_et3000, svga_et4000,
svga_paradise, vesa_nolfb, vesa_oldvbe.

-c <command> Run the specified DOS command before handling the PATH.
Multiple commands can be specified.

--noautoexec Don't run DOS commands from any [autoexec] sections.

--exit Exit after running '-c <command>'s and [autoexec] sections.

--startmapper Run the mapper GUI.

--erasemapper Delete the default mapper file.

--securemode Enable secure mode by disabling the MOUNT and IMGMOUNT
commands.

--socket <num> Run nullmodem on the specified socket number.

--help Print help message and exit.

--version Print version information and exit.

INTERNAL COMMANDS

dosbox has a comprehensive internal help system which can be accessed by running HELP command.

dosbox supports most of the DOS commands found in COMMAND.COM. In addition, the following extra commands are frequently used:

MOUNT

Program to mount local directories as drives inside dosbox.

IMGMOUNT

A utility to mount disk images and CD‐ROM images in dosbox.

CONFIG

Change dosbox internal configuration on the fly. May not work with all options.

LOADFIX

Program to reduce the amount of memory available. Useful for old programs which don't expect much memory to be free.

RESCAN

Make dosbox reread the directory structure. Useful if you changed something on a mounted drive outside dosbox. Ctrl+F4 does this as well.

BOOT

BOOT will start floppy images or hard disk images independent of the operating system emulation offered by dosbox. This will allow you to play booter floppies or boot to other operating systems inside dosbox.

FILES

Configuration and language files use a format similar to Windows .ini files. If no configfile is specified at the commandline, a file named dosbox-staging.conf (if present in the current directory) will be loaded automatically. We also will read and load dosbox.conf locally too, if dosbox-staging.conf isn't present.

If a configfile is specified at the commandline that one will be used instead. If no configfile is specified or found in the current directory then dosbox will load one from $XDG_CONFIG_HOME/dosbox/ (which defaults to ~/.config/dosbox/). It will try to create a new default config file if it does not exist yet.

SPECIAL KEYS

Alt+Enter: Switch between fullscreen and window mode.
Alt+Pause: Pause/Unpause emulator.
Ctrl+F1: Start the keymapper.
Ctrl+F4: Swap mounted disk‐image (only used with imgmount). Update directory cache for all drives.
Ctrl+F5: Save a screenshot of the DOS pre-rendered image.
Alt+F5: Save a screenshot of the rendered image.
Ctrl+F6: Start/Stop recording sound output to a wave file.
Ctrl+F7: Start/Stop recording video output to a zmbv file.
Ctrl+F8: Mute/Unmute the audio.
Ctrl+F9: Kill dosbox.
Ctrl+F10: Capture/Release the mouse.
Ctrl+F11: Slow down emulation (Decrease number of cycles/s).
Ctrl+F12: Speed up emulation (Increase number of cycles/s).
Alt+F12: Unlock speed (turbo button).

These are the default keybindings. They can be changed in the keymapper. More bindable actions can be found in the keymapper.

NOTES

Saved/recorded files can be found in current_directory/capture (can be changed in the configfile). The directory has to exist prior to starting dosbox else nothing gets saved/recorded!

Once you increase your dosbox cycles beyond your computer's maximum capacity, it will produce the same effect as slowing down the emulation. This maximum will vary from computer to computer, there is no standard.

ENVIRONMENT

Any configuration option can be override using an environment variable. Environment variables starting with prefix DOSBOX are processed and interpreted as follows: DOSBOX_SECTIONNAME_PROPERTYNAME=value

For example, you can override Sound Blaster type to Sound Blaster Pro 2 this way:

$ DOSBOX_SBLASTER_SBTYPE=sbpro2 dosbox

BUGS

To report a bug, please visit https://github.com/dosbox-staging/dosbox-staging/issues

AUTHOR

DOSBox Staging project is maintained by the DOSBox Staging Team (https://www.dosbox-staging.org/)

This manual page was written by Peter Veenstra <H.P.Veenstra@student.rug.nl> and James Oakley <jfunk@funktronics.ca>, for the Debian system (but may be used by others), updated by Patryk Obara <dreamer.tan@gmail.com> and Antti Peltola <antti.peltola@kolumbus.fi> for DOSBox Staging project.