DOSBOX-X(1)

🌸 DOSBOX-X(1) — dosbox-x 🌸

okay bestie, sit DOWN, because we're about to read the manual for dosbox-x from the dosbox-x manual section, and it's a whole ✨journey✨. no cap.

---

✨ NAME ✨

dosbox-x — an x86/DOS and PC98 emulator 💖 (yes, that's the whole vibe. emulator. iconic.)

---

✨ SYNOPSIS ✨

dosbox-x [OPTIONS] [FILE]

that's it. that's the whole thing. look at her go 🎀

---

✨ DESCRIPTION ✨

okay so this manual page briefly documents DOSBox-X, which is an x86/DOS and PC98 emulator. briefly!! they said briefly!! 😭

the options are all listed below, and depending on which option you're looking at, you might be able to specify one of them, or honestly several of them. mix and match, it's giving build-your-own-adventure.

now. the optional FILE argument. listen closely because this part is lowkey important:

• it should be a DOS executable or a directory.
• if it's a DOS executable (think .com, .exe, .bat), the program just runs automatically. no extra steps, she's self-sufficient 💅
• if it's a directory, then that directory gets mounted as the C:\ drive. cute, right?
• and if your DOS executable needs parameters? enclose the command and its parameters in quotes. the original says "it's parameters" and honestly we're keeping the typo's spirit alive, but the takeaway is: quotes around the whole thing.

and for an introduction, type INTRO inside dosbox-x. that's your tutorial era. go get it 🦋

---

✨ OPTIONS ✨

a summary of the available options. here we go, this is the long part, stay with me 🫶

• -?, -h or -help — shows you the help screen and then exits. the classic "hi, bye" 💀
• -v, -ver or -version — displays the version information and exits.
• -fullscreen, -fs — starts dosbox-x in fullscreen mode. immersive. main character energy 👑
• -machine machinetype — starts dosbox-x with a specific machine type. valid choices are, and buckle up because this list is long:
  • mda — IBM Monochrome Display Adapter, and it's text only, bestie.
  • hercules — Hercules Graphics Card, and she's monochrome.
  • cga — IBM Color Graphics Adapter, with automatic RGB/Composite switching. fancy.
  • cga_mono — IBM CGA attached to a monochrome display.
  • cga_rgb — IBM CGA attached to an RGB monitor.
  • cga_composite — IBM CGA (early revision) attached to an NTSC TV.
  • cga_composite2 — IBM CGA (late revision) attached to an NTSC TV.
  • pcjr — IBM PCjr.
  • pcjr_composite — IBM PCjr (late revision) attached to NTSC TV.
  • pcjr_composite2 — IBM PCjr (late revision) attached to NTSC TV.
  • tandy — Tandy 1000 Graphics Adapter.
  • amstrad — Amstrad PC1512 graphics mode.
  • ega — IBM Enhanced Graphics Adapter.
  • jega — Japanese Enhanced Graphics Adapter (Microsoft AX).
  • mcga — IBM Multi-Color Graphics Array.
  • vgaonly — IBM Video Graphics Array (see below — yes there's a whole thing about this one, keep reading).
  • svga_paradise — SVGA - Paradise Systems PVGA1A.
  • svga_et3000 — SVGA - Tseng Labs ET3000.
  • svga_et4000 — SVGA - Tseng Labs ET4000.
  • svga_s3 — VESA SVGA - S3 Trio64 - VBE 2.0.
  • svga_s386c928 — VESA SVGA - S3 86c928 - VBE 2.0 (experimental 🧪).
  • svga_s3vision864 — VESA SVGA - S3 Vision 864 - VBE 2.0.
  • svga_s3vision868 — VESA SVGA - S3 Vision 868 - VBE 2.0.
  • svga_s3vision964 — VESA SVGA - S3 Vision 964 - VBE 2.0.
  • svga_s3vision968 — VESA SVGA - S3 Vision 968 - VBE 2.0.
  • svga_s3trio32 — VESA SVGA - S3 Trio32 - VBE 2.0.
  • svga_s3trio64 — VESA SVGA - S3 Trio64 - VBE 2.0 (same as svga_s3).
  • svga_s3trio64v+ — VESA SVGA - S3 Trio64V+ - VBE 2.0.
  • svga_s3virge — VESA SVGA - S3 ViRGE - VBE 2.0 (experimental 🧪).
  • svga_s3virgevx — VESA SVGA - S3 ViRGE VX - VBE 2.0 (experimental 🧪).
  • vesa_oldvbe — VESA SVGA - S3 Trio64 with VESA BIOS Extensions (VBE) 1.2.
  • vesa_oldvbe10 — VESA SVGA - S3 Trio64 with VESA BIOS Extensions (VBE) 1.0.
  • vesa_nolfb — VESA SVGA - S3 Trio64 with VBE 2.0 with Linear Frame Buffer disabled.
  • pc98 — Japanese NEC PC-98 emulation.
  • pc9801 — same as pc98.
  • pc9821 — same as pc98.
  • fm_towns — Japanese Fujitsu FM Towns (not implemented 🙈 don't get your hopes up).

the default is svga_s3. periodt.

for some special VGA effects you can use the machinetype vgaonly. but bestie, heads up: note that this disables SVGA capabilities and it might be slower because of the higher emulation accuracy. tradeoffs!! we love an accurate queen who takes her time 💅

Note — the machinetype doesn't just affect the emulated video card. it may also affect the available sound cards. so like, choose wisely, iykyk.

• -conf configfile — starts dosbox-x with the options specified in configfile. this file can also have a section called [autoexec] where you put commands you want executed on startup. and here's the cute part: you can specify multiple -conf options with configfiles, and they'll be overlaid on each other. layer cake 🎂
• -editconf [editor] — opens the default configuration file in a text editor. if you don't give an editor name, it uses the program from the EDITOR environment variable. let the environment decide, she's independent.
• -userconf — loads the configuration file located in ~/.config/dosbox-x. can be combined with the -conf option. they're friends 🫶
• -printconf — prints the location of the default configuration file and exits.
• -eraseconf, -resetconf — removes the default configuration file and exits. gone. deleted. 🗑️
• -erasemapper, -resetmapper — removes the mapperfile configured in the clean default configuration file and exits.
• -opencaptures program — calls program with, as its first parameter, the location of the captures folder, and exits.
• -opensaves program — calls program with, as its first parameter, the location of the saves folder, and exits.
• -startui, -startgui or -starttool — starts DOSBox-X with the GUI configuration tool. point and click era ✨
• -startmapper — starts the internal keymapper on startup of dosbox-x. you can use it to change the keys dosbox-x uses. remap your whole life.
• -promptfolder — prompts for the working directory when DOSBox-X starts.
• -nopromptfolder — does not prompt for the working directory when DOSBox-X starts. the opposite of the one above, and honestly? iconic duo.
• -nogui or -nomenu — don't show the GUI menu bar when in windowed mode. minimalism 🎀
• -showcycles — shows the cycles count (FPS) in the title.
• -showrt — shows the emulation speed relative to realtime in the title.
• -socket socketnumber — passes the TCP socket number socketnumber for the nullmodem emulation. see the WIKI for details.
• -savedir path — sets path for the save slots.
• -defaultdir path — sets path as the default working path for DOSBox-X.
• -defaultconf — uses the default config settings for DOSBox-X.
• -defaultmapper — uses the default key mappings for DOSBox-X.
• -data-host-forced — forces synchronization of date and time with the host. your clock, but make it their clock 🕐
• -display2 [color] — enables both standard & monochrome dual-screen mode. the monochrome display defaults to white, but you can optionally set it to green or amber. two screens, one queen.
• -lang message_file — starts dosbox-x with the language specified in message_file. multilingual slay 🌈
• -nodpiaware — ignores (does not signal) Windows DPI awareness.
• -securemode — enables secure mode, which is meant to prevent a DOS program potentially gaining access to files outside directories mounted in the [autoexec] section of the config file. it does this by running Z:\SYSTEM\CONFIG.COM -securemode after completing the [autoexec] section (which in turn disables any changes to how the drives are mounted "inside" dosbox-x). it also disables various other CONFIG.COM options that could be exploited. safety first, bestie 🔒
• -prerun — if FILE is given, runs it before the AUTOEXEC.BAT config section.
• -hostrun — enables the START command, the CLIP$ device, and long filename (LFN) support.
• -noconfig — skips the [config] section of the loaded configuration file. this is equivalent to skipping CONFIG.SYS in DOS.
• -noautoexec — skips the [autoexec] section of the loaded configuration file. this is equivalent to skipping AUTOEXEC.BAT in DOS.
• -exit — dosbox-x will close itself when the DOS program specified by FILE ends. she leaves when the party's over 💀
• -silent — runs DOSBox-X silently and exits after executing the [autoexec] section of the loaded config file. ninja mode 🥷
• -o option(s) — provides command-line option(s) for [FILE] if specified.
• -c command — runs the specified command before running [FILE]. multiple commands can be specified, but each command should start with -c though. a command can be an Internal Program, a DOS command, or an executable on a mounted drive. if the command requires parameters, enclose the command and its parameters in quotes. stack 'em up 🥞
• -set section property=value — sets the config option (and overrides any config file). if the property contains spaces, make sure to enclose the string in quotes. the section is the name of a dosbox-x config section such as [video] without the brackets. multiple -set commands may be specified. and if a property is unique, the section can be omitted — like, -set sdl output=ttf is equivalent to -set output=ttf. so efficient. so her 💅
• -time-limit seconds — kills the emulator after seconds. dramatic but punctual ⏰
• -fastlaunch — fast launch mode. it skips the BIOS logo and the welcome banner. no small talk, straight to business.
• -helpdebug — shows debug-related options and exits. for the tech girlies 🧚

---

✨ INTERNAL INTERPRETER COMMANDS ✨

okay so dosbox-x supports most of the internal DOS commands you'd find in COMMAND.COM. help text is integrated for these commands in DOSBox-X, and it will not be duplicated here. an explanation of these commands can also be found on the DOSBox-X wiki, on the Supported Commands page.

here's the whole roster, alphabetically iconic:

ALIAS, ATTRIB, BREAK, CALL, CD/CDDIR, CHCP, CHOICE, CLS, COPY, COUNTRY, CTTY, DATE, DEL/ERASE, DELTREE, ECHO, EXIT, DIR, FOR, GOTO, HELP, IF, LFNFOR, LH/LOADHIGH, MD/MKDIR, MORE, PATH, PAUSE, PROMPT, RD/RMDIR, REM, REN/RENAME, SET, SHIFT, SUBST, TIME, TRUENAME, TYPE, VER, VERIFY, VOL

---

✨ OTHER PROVIDED COMMANDS ✨

and there's MORE, because in addition, the following extra commands are available on the emulated Z: drive:

Note — some commands (like NE2000) are only present in case the corresponding feature is enabled. so if it's missing, check your features, bestie 🫶

• Z:\4DOS — 4DOS, 4HELP, OPTION, BATCOMP
• Z:\BIN — EVAL, SHUTDOWN, DSXMENU, CWSDPMI, EMSMAGIC, UNZIP, ZIP, MPXPLAY, DOSMID, CDPLAY, DOS4GW, DOS32A, DOSIDLE, UTF16, UTF8, AUTOTYPE, ADDKEY, LS, TITLE, COLOR, SETCOLOR
• Z:\DOS — MEM, EDIT, PRINT, DISKCOPY, DEFRAG, FORMAT, FDISK, SYS, FC, COMP, CHKDSK, BUFFERS, DEVICE, APPEND, XCOPY, SORT, REPLACE, LASTDRIV, FILES, FCBS, FIND, MOVE, DEBUG, EDLIN, CHOICE, DELTREE, TREE, LABEL, LOADFIX, MOUSE, MODE, KEYB
• Z:\DEBUG — HEXMEM32, HEXMEM16, A20GATE, BIOSTEST, INT2FDBG, NMITEST, LOADROM, VESAMOED, VFRCRATE
• Z:\SYSTEM — PARALLEL, SERIAL, MIXER, CAPMOUSE, FLAGSAVE, CFGTOOL, RESCAN, RE-DOS, COUNTRY, CONFIG, BOOT, MOUNT, IMGSWAP, IMGMAKE, IMGMOUNT, INTRO, HELP, NE2000
• Z:\TEXTUTIL — CGA, CLR, EGA, VGA, DCGA, 132X25, 132X43, 132X50, 132X60, 80X25, 80X50, 80X60

---

and that's where part 1 wraps, because there is so much more coming and we are nowhere near done yet 🌈✨

✨ SPECIAL KEYS ✨

okay bestie, these are the default keyboard combos and they are lowkey iconic 💅 some of them only do stuff depending on which emulation you've got running, so read the lil labels, fr fr.

• CTRL-F7 — CGA emulation only — flip between early model and late model IBM CGA emulation 🎀
• CTRL-F8 — CGA emulation only — cycle between Auto, RGBI and Composite monitor output emulation ✨
• CTRL-SHIFT-F7 — CGA emulation only — decrease Hue 🌈
• CTRL-SHIFT-F8 — CGA emulation only — increase Hue 🌈
• CTRL-F7 — CGA Mono and Hercules emulation only — cycle between Green, Amber, White and Grey 👑
• CTRL-F8 — CGA Mono and Hercules emulation only — cycle between low and high brightness 💡
• F12-F — switch between fullscreen and window mode 🖥️
• F12-R — Reset the virtual machine inside DOSBox-X 🔄
• F12-B — Reboot the emulated DOS (integrated DOS or guest DOS) inside DOSBox-X 🔁
• F12-C — Start DOSBox-X's graphical configuration tool ⚙️
• F12-M — Start DOSBox-X's mapper editor 🗺️
• F12-Esc — Show/hide DOSBox-X's drop-down menu bar 📋
• F12-Del — Send the selected special key combination (Ctrl+Alt+Del by default) to the guest system 💀
• F12-{+} — Increase the sound volume of DOSBox-X's emulated DOS 🔊
• F12-{-} — Decrease the sound volume of DOSBox-X's emulated DOS 🔉
• F12-] — Increase the emulated DOS's current speed relative to real-time ⏩
• F12-[ — Decrease the emulated DOS's current speed relative to real-time ⏪
• F12-{=} — Increase DOSBox-X's emulation CPU cycles 🔥
• F12-{-} — Decrease DOSBox-X's emulation CPU cycles 🔥
• F12-Up — Increase the font size for the TrueType font (TTF) output 🔍
• F12-Down — Decrease the font size for the TrueType font (TTF) output 🔍
• F12-Left — Reset the emulated DOS's current CPU speed to the normal speed ⏱️
• F12-Right — Toggle DOSBox-X's speed lock 🔒
• F12-D — Swap between mounted CD images 💿
• F12-O — Swap between mounted floppy images 💾
• F12-P — Take a screenshot of the current screen in PNG format 📸
• F12-I — Start/Stop capturing an AVI video of the current session 🎥
• F12-W — Start/Stop recording a WAV audio of the current session 🎙️
• Alt+Pause — Start DOSBox-X's Debugger 🐛
• F12-[,] — Select the previous save slot to save to or load from ⬅️
• F12-[.] — Select the next save slot to save to or load from ➡️
• F12-S — Save current state to the selected save slot 💾
• F12-L — Load the state from the selected save slot 📂
• F12-Pause — Pause emulation (press again to continue) ⏸️
• Ctrl+F5 — Copy all text on the DOS screen to the host clipboard 📋
• Ctrl+F6 — Paste the text in the host clipboard to the DOS screen 📥
• Ctrl+F9 — Exit DOSBox-X 🚪
• Ctrl+F10 — Capture the mouse for use with the emulated DOS 🖱️

These are the default keybindings. They can be changed in the keymapper. ✨

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-x else nothing gets saved or recorded! 😭 no cap, it will just silently not save and you'll be sad.

Note Once you increase your dosbox-x 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 overridden 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 the render aspect this way:

$ DOSBOX_RENDER_ASPECT=false dosbox-x

---

🐛 BUGS 🐛

To report a bug, please visit https://github.com/joncampbell123/dosbox-x/issues 🫶 the maintainers do read them, bestie.

---

📚 RESOURCES 📚

• project web site: https://dosbox-x.com 🌐
• Project Wiki: https://dosbox-x.com/wiki 📖

---

👑 AUTHOR 👑

DOSBox-X is maintained by the DOSBox-X Team 💜

---

and that's the whole page, bestie!! 🎀 this was DOSBOX-X(1), dated 2022-04-26 — go forth and emulate, you absolute icon 🌟✨🦋