PCBASIC(1)
๐ PCBASIC โ the manual, but make it make sense (part 1) ๐
okay bestie, gather round โ this is the manual page for pcbasic, from the General Commands Manual section. Yes, section 1, the "user commands" section, the one where all the fun stuff lives. Let's get into it. ๐ซถ
โจ NAME โจ
pcbasic โ a free, cross-platform emulator for the GW-BASIC family of interpreters. That's the whole vibe. One name, one job, endless nostalgia. ๐
๐ธ DESCRIPTION ๐ธ
So. PC-BASIC is a free, cross-platform interpreter for GW-BASIC, Advanced BASIC (that's BASICA), PCjr Cartridge Basic, and Tandy 1000 GWBASIC. It interprets all of these BASIC dialects with a high degree of accuracy, and honestly the goal is bug-for-bug compatibility โ like, it is not trying to fix the quirks, it is trying to BE the quirks. Iconic behaviour, no notes. ๐
On top of that, PC-BASIC emulates the most common video and audio hardware that these BASICs used to run on, so it's giving full era-accurate main character energy. ๐บ๐
It runs plain-text, tokenised and protected .BAS files โ all three, no discrimination.
And here's the flex: it implements floating-point arithmetic in the Microsoft Binary Format (MBF), which means it can read and write binary data files that were created by GW-BASIC. fr fr. Same bytes, same energy. ๐ง
โญ SYNOPSIS โญ
pcbasic [program|package [output]] [OPTION] ...
๐ POSITIONAL ARGUMENTS ๐
Real talk, the rules here are strict and they do not care about your feelings:
Positional arguments must come before any options. They must not start with a dash -. And any positional arguments that come after options? Ignored. Just straight up ignored. ๐
programโ if a.BASprogram is the first positional argument, it gets run. Simple. But heads up: the--run,--loadand--convertoptions override this behaviour, so they're the ones calling the shots. ๐packageโ if a zipfile package or a directory is the first positional argument, then anyPCBASIC.INIconfiguration file contained inside it gets loaded, and usually it'll run a program file inside that package. Every other command-line option overrides the package configuration file โ and note in particular the potential of the--run,--loadand--convertoptions to alter the behaviour of the package. So the package is a starting point, not the boss. ๐outputโ if there's a second positional argument, it sets the output file for file format conversion. This one is ignored unless the--convertoption is given. Ignored! Sitting there! Doing nothing! We've all been there bestie. ๐ซ
๐ฅ OPTIONS ๐ฅ
Okay this is the long part, hydrate first. ๐
--allow-code-poke[=True|=False]โ allow programs toPOKEinto code memory. Yes, that's exactly as spicy as it sounds.--aspect=x,yโ set the display aspect ratio tox:y. Only has an effect if combined with--interface=graphical.-bโ use the command-line interface. This is identical to--interface=cli.--border=widthโ set the width of the screen border as a percentage from0โ100. That percentage refers to the total width of the borders on both sides as a fraction of the usable screen width. Only has an effect if combined with--interface=graphical.-c=statement[:statement ...]โ execute commands as a shell. This is a convenience shorthand and it's identical to--interface=none --quit=True --exec=statement[:statement ...]. One tiny flag, three flags' worth of chaos. slay. โจ--caption=titleโ set the title bar caption of the PC-BASIC window. Default title isPC-BASIC.--cas1=type:valueโ attach a resource to theCAS1:cassette device.type:valuecan be:WAV:wav_fileโ connect to the RIFF Wave filewav_filewith data modulated in IBM PC cassette format.CAS:cas_fileโ connect to the PCE/PC-BASIC CAS tape imagecas_file.
--codepage=codepage_id[:nobox]โ load the specified codepage. The codepage determines which characters are associated to a given character byte or, in the case of double-byte codepages, two character bytes. The available codepages live in thecodepage/directory; by default these are:
437 720 737 775 806 850 851 852 853 855 856 857 858 860 861 862 863 864 865 866 868 869 874 932 934 936 938 949 950 1258 alternativnyj armscii8a big5-2003 big5-hkscs georgian-academy georgian-ps iransystem iscii-as iscii-be iscii-de iscii-gu iscii-ka iscii-ma iscii-or iscii-pa iscii-ta iscii-te kamenicky koi8-r koi8-ru koi8-u mazovia mik osnovnoj pascii ruscii russup3 russup4ac russup4na viscii
See the list of codepages in the User's Guide for details. The specifier nobox disables box-drawing recognition for double-byte character set code pages. By default, sequences of box-drawing characters are recognised by an algorithm that isn't as smart as it thinks it is, and displayed as box drawing rather than as DBCS characters. If nobox is set, they will be displayed as DBCS.
--config=config_fileโ read a configuration file. The system default configuration is always read first, but any preset group of options in a configuration file replaces the whole equivalent default preset group. Whole group, not just one option. Respect the group. ๐ซถ--com1=type:valueโ attach a resource to theCOM1:serial device.type:valuecan be one of the following:PORT:device_nameโ connect to a serial device.device_namecan be a device name such asCOM1or/dev/ttyS0, or a number, where the first serial port is number0.SOCKET:host:socketโ connect to a TCP socket on a remote or local host.RFC2217:host:socketโ connect using the RFC2217 protocol to a TCP socket on a remote or local host.STDIO:[CRLF]โ connect to standard I/O of the calling shell. IfCRLFis specified, PC-BASIC replaces CR characters with LF on its output and LF with CR on its input. This is more intuitive on Unix shells. When using a Unix console, you should usestty -icanonto enable PC-BASIC to read input correctly.
If this option is not specified, the COM1: device is unavailable.
--com2=type:valueโ attach a resource to theCOM2:serial device. See--com1. Same deal, second port. ๐ซ--convert={A|B|P}โ convert program to one of the following formats:Aโ Plain textBโ TokenisedPโ Protected
If output is not specified, write to standard output. If program is not specified, use the argument of --run or --load. If none of those are given, read from standard input. Overrides --resume, --run and --load.
--mouse-clipboard[=True|=False]โ enable clipboard operations with the mouse. IfTrue(default), select text with the left mouse button to copy and paste with the middle mouse button. Copy-paste, the classic combo. ๐ฑ๏ธ--ctrl-c-break[=True|=False]โ ifFalse, follow GW-BASIC behaviour whereCtrl+CbreaksAUTOandINPUTbut not program execution orLIST. IfTrue, treatCtrl+Cexactly likeCtrl+BreakandCtrl+Scroll Lockwhen--interface=graphical. With--interface={text|cli},Ctrl+Cis always treated likeCtrl+Break. Default isTrue.--current-device={CAS1|@|A|B ... |Z}โ set the current device to the indicated PC-BASIC drive letter, orCAS1for the cassette device. The device you choose should be mounted to an actual location using--mount(or--cas1if you picked the cassette device). Don't leave it floating, mount your drives bestie. ๐พ--debug[=True|=False]โ developer option โ use only if you know what you're doing. Enable debugging extension.--dimensions=x,yโ set window dimensions toxbyypixels. This overrides--scaling=nativeand--aspect. Only has an effect if combined with--interface=graphical.-d,--double[=True|=False]โ enable double-precision transcendental math functions. This is equivalent to the/doption in GW-BASIC. More precision, more power. ๐ฅ-e=statement[:statement ...],--exec=statement[:statement ...]โ execute BASIC statements. The statements are executed after loading any program but before entering into direct mode or running it. Multiple statements can be entered by separating them with colons:. These will be executed as if they were entered as separate statements, not as a single compound statement: even if statements such asGOTOorLISTare included, the following statements will still be executed. The character:will be interpreted as part of a string if quoted with single quotes". If your calling shell interprets such quotes, you should properly escape them. (Shell quoting is the villain of every story, ngl.)--extension=module_name[,module_name ... ]โ developer option โ use only if you know what you're doing. Load extension module(s).--font=font_name[,font_name ... ]โ use the specified fonts for the interface. The last fonts specified take precedence, previous ones are fallback. The available fonts are stored infont/. By default, the following fonts are available:
default cga mda vga olivetti tandy1 tandy2
The font names freedos, univga, and unifont are treated as synonyms of default unless a font with one of these names is available. This behaviour is deprecated and these synonyms will be removed in a future version. See the list of fonts in the User's Guide for details.
--fullscreen[=True|=False]โ fullscreen mode. Only has an effect if combined with--interface=graphical. Big screen, big vibes. ๐ฅ๏ธ-h,--helpโ show a usage message and exit.--hide-listing=line_numberโ disable listing and saving to plain text of lines beyondline_number, as in GW-BASIC beyond65530.
Use with care as this allows execution of hidden lines of code. ๐จ
Default is to list all lines.
--hide-protected[=True|=False]โ disable listing and saving to plain text of protected files, as in GW-BASIC.
Use with care as this allows execution of hidden lines of code. ๐จ
-i={input_file|{STDIO|STDIN}[:RAW]},--input={input_file|{STDIO|STDIN}[:RAW]}โ retrieve keyboard input frominput_file, except ifKYBD:is read explicitly. Input fromKYBD:files is always read from the keyboard, following GW-BASIC behaviour. Ifinput_fileisSTDIO:orSTDIN:, keyboard input will be read from standard input. IfRAWis specified, input will be treated as codepage bytes. If not, it will be treated as the locale's encoding (probably UTF-8).--interface=[none|cli|text|graphical]โ choose the type of interface. Not all interfaces will be available on all systems. The following interface types may be available:noneโ filter for use with pipes. Also-n.cliโ command-line interface. Also-b.textโ ANSI text interface. Also-t.graphicalโ SDL2 graphical interface.
The following values for this option are deprecated:
ansiโ ANSI text interface. Synonym fortext.sdl2โ SDL2 graphical interface. Synonym forgraphical.pygameโ PyGame graphical interface. Please usegraphicalinstead.cursesโ NCurses text interface. Please usetextinstead.
The default is graphical. ๐
okay that's a lot of options and we're not even done โ part 2 is coming, stay with me bestie ๐
-k=keystring,--keys=keystringโ Insert thekeystringinto the keyboard buffer ๐ .keystringmay contain escape codes such as\rfor return,\nfor line feed and\xXXto enterCHR$(&HXX). It may also contain e-ASCII codes to indicate keypresses that do not have a regular character encoding. For example,\0\x0Findicates Shift+Tab โจ.-l=program,--load=programโ Start in direct mode with the BASIC program loaded ๐ซถ.--logfile=log_fileโ Write error and warning messages tolog_fileinstead ofstderr๐.--lpt1=type:valueโ Decide where the output goes when writing to theLPT1:parallel device.type:valuecan be:PRINTER:[printer_name][:trigger]โ Output is written to a printer. Ifprinter_nameis not specified, the default printer is used. Windows and CUPS printers are supported. The printer will be activated when a file onLPT1:triggersets an additional trigger to activate the printer:lineโ After every line break.pageโ After every page break.closeโ No additional trigger.- The default is
close.
FILE:file_nameโ Output is written to a file or character device such as/dev/stdouton Unix orLPT1on Windows.STDIO:โ Output is written to the standard output of the calling shell.PARPORT:port_numberโ Output is written to a Centronics parallel port, whereport_numberis0for the first parallel port, etc. This option only works with physical parallel ports. To write to a Windows printer or other device mapped withNET USE LPT1:, useFILE:LPT1instead.- The default is
PRINTER:, so that output goes to the default printer specified by the operating system.
--lpt2=type:valueโ Attach a resource to theLPT2:parallel device. See--lpt1. Note that, unlikeLPT1:, printers connected toLPT2:do not get activated when a program terminates. If this option is not specified,LPT2:is unavailable ๐.--lpt3=type:valueโ Attach a resource to theLPT3:parallel device. See--lpt1. Note that, unlikeLPT1:, printers connected toLPT3:do not get activated when a program terminates. If this option is not specified,LPT3:is unavailable ๐.-f=number_of_files,--max-files=number_of_filesโ Set maximum number of open files tonumber_of_files. This is equivalent to the/foption in GW-BASIC. Default is3๐.--max-memory=max_memory[,basic_memory_blocks]โ Set the maximum size of the data memory segment tomax_memoryand the maximum size of the data memory available to BASIC tobasic_memory_blocks*16. In PC-BASIC, the minimum of these values is simply the data memory size; the two values are allowed for compatibility with the/moption in GW-BASIC ๐ง .-s=record_length,--max-reclen=record_lengthโ Set maximum record length forRANDOMfiles torecord_length. Default is128, maximum is32767. This is equivalent to the/soption in GW-BASIC ๐.--monitor={rgb|composite|green|amber|grey|mono}โ Sets the monitor type to emulate. Available types are:rgbโ RGB colour monitor (default).compositeโ Composite colour monitor.greenโ Green-tinted monochrome monitor.amberโ Amber-tinted monochrome monitor.greyโ Greyscale monochrome monitor.monoโ Green-tinted monochrome monitor (same asgreen).- On
SCREEN 2with--video={pcjr|tandy|cga},--monitor=compositeenables (crude) colour artifacts ๐.
--mount=[drive:path[,drive:path ... ]]โ Assign the pathpathto drive letterdrive:. The path can be absolute or relative. If this option is not specified: on Windows, all Windows drive letters will be assigned to PC-BASIC drive letters; on other systems, the current working directory is assigned toZ:. If this option is specified but empty, do not mount any drives (except the internal device@:) ๐๏ธ.-nโ Run PC-BASIC as a command-line filter. Same as--interface=none๐ง.-o=output_file[:append],--output=output_file[:append]โ Send screen output tooutput_file, except ifSCRN:is written to explicitly. Output toSCRN:files will always be shown on the screen, as in GW-BASIC. If the specifierappendis given, the output file is appended to rather than overwritten. Ifoutput_fileisSTDIO:orSTDOUT:, screen output will be sent to standard output ๐บ.--peek=[seg:addr:val[,seg:addr:val ... ]]โ DefinePEEKpreset values. If defined,DEF SEG seg:? PEEK(addr)will returnval๐.--preset=option_blockโ Load machine preset options. A preset option corresponds to a section defined in a config file by a name between square brackets, like[this]โ--preset=thiswill load all settings defined in that section. Available presets depend on your configuration file. See the list of default presets in the User's Guide ๐.--prevent-close[=True|=False]โ Suppress window close event. This allows BASIC to capture key combinations that normally close the window. Graphical interface only. By default, the operating system's key combination to close a window (usuallyAlt+F4) terminates PC-BASIC. Set--prevent-closeto allow BASIC to capture this key combination instead. This is useful if your program uses this key combination ๐ซ๐ช.-q,--quit[=True|=False]โ Quit interpreter when execution stops. If combined with--run, PC-BASIC quits when the program ends. If set in direct mode, PC-BASIC quits after the first command is executed ๐.--reserved-memory=number_of_bytesโ Reservenumber_of_bytesof memory at the bottom of the data segment. For compatibility with GW-BASIC. Default is3429bytes. Lowering this value makes more string and variable space available for use by programs ๐งฎ.--resume[=True|=False]โ Resume from saved state. Overrides--runand--loadโฏ๏ธ.-r=program,--run=programโ Run the specified program. Overrides--load๐โโ๏ธ.--scaling={smooth|crisp|native}โ Choose scaling method.smoothโ The display is smoothly scaled to the largest size that allows for the correct aspect ratio.crispโ The display is scaled to the same size as withsmooth, but without smoothing.nativeโ Scaling and aspect ratio are optimised for the display's native pixel size, without smoothing.--scaling=nativeoverrides--aspect.- Default is
smooth. Only has an effect if combined with--interface=graphical๐ผ๏ธ.
--serial-buffer-size=sizeโ Set serial input buffer size. Default is256. If set to0, serial communications are disabled ๐.--shell=[shell-executable]โ Enable theSHELLstatement to run the operating system command interpretershell-executable. The executableshell-executableshould support MS-DOS'sCOMMAND.COMcalling conventions, in particular its/Cswitch. Example command interpreters areCMD.EXEon Windows and"wine cmd.exe"on Unix. Ifshell-executableis empty (as it is by default), theSHELLstatement is disabled ๐.--soft-linefeed[=True|=False]โ Do not treatLFin text and program files as a line break. This enables the highest level of compatibility with GW-BASIC files. If this option is set, any Linux or Mac text files need to be converted to DOS text before using them with PC-BASIC ๐.--sound[=True|=False]โFalseโ Suppress sound output.Trueโ Output sound, if a sound driver is available (default).- If sound is on, PC-BASIC will try to use the SDL2 library first; if it is not available, it will try PortAudio. If neither is available, sound will be disabled. The following values for this option are deprecated:
noneโ Suppress sound output. UseFalseinstead.interfaceโ Use the native sound engine of the interface. UseTrueinstead.sdl2โ Use the SDL2 sound generator.portaudioโ Use the PortAudio sound generator.beepโ Use the built-in speaker. ๐
--state=state_fileโ Set the save-state file tostate_file. Default ispcbasic.sessionin the Application Data directory ๐พ.--syntax={advanced|pcjr|tandy}โ Choose BASIC dialect. Available dialects are:advancedโ IBM BASICAgwbasicโ Microsoft GW-BASICpcjrโ IBM PCjr Cartridge BASICtandyโ Tandy 1000 GW-BASIC.- Default is
advanced๐งฌ.
-tโ Use text-based interface. Same as--interface=text๐.--term=terminal_programโ Set the terminal program run by the PCjrTERMcommand toterminal_program. This only has an effect with--syntax={pcjr|tandy}๐ฅ๏ธ.--text-width={40|80}โ Set the number of columns in text mode at startup. Default is80๐.--text-encoding=[encoding]โ Set the text encoding. Text files (i.e. plain-text programs and files opened forINPUTandOUTPUT) stored on a disk device will be assumed to be encoded inencoding. Examples of valid encodings areutf-8,utf-16,latin-1. Please ensure that all characters in the current codepage are included in the encoding you choose; if this is not the case then such characters will be replaced by๏ฟฝor?. Ifencodingis not set, text files will be treated as raw bytes in the current PC-BASIC codepage ๐ค.--utf8[=True|=False]โ Set the text encoding to UTF-8. This option is deprecated and ignored if--text-encodingis set. Use--text-encoding=utf-8instead ๐ซ.-v,--versionโ Print PC-BASIC version string and exit ๐ท๏ธ.--video=adapterโ Set the video adapter to emulate. Available adapters:vgaโ Video Graphics Arrayegaโ Enhanced Graphics Adaptercgaโ Color/Graphics Adaptermdaโ Monochrome Display Adapterherculesโ Hercules Graphics Adapterpcjrโ IBM PCjr graphicstandyโ Tandy 1000 graphicsolivettiโ Olivetti M24 graphics- Default is
vga๐ฎ.
--video-memory=sizeโ how much emulated video memory you get to play with. This is the thing that decides how many video pages you can use. On PCjr and Tandy you can literally change it mid-session with theCLEARstatement, and heads up: you need at least32768available beforeSCREEN 5andSCREEN 6will let you in the door. Default is16384on PCjr and Tandy, and262144on the other machine presets.-w,--wait[=True|=False]โ ifTrue, PC-BASIC sits there and waits for a keystroke before it closes the window on exit. Only works when--interface=graphicalor--interface=text, so don't expect it to do anything otherwise. Default isFalse.--options=gwbasic_optionsโ sets GW-BASIC-style command-line switches. This is purely a convenience thing to make migrating from GW-BASIC less of a whole ordeal.gwbasic_optionsis a string that can contain these bad boys:/dโ turns on double-precision floating-point math functions. See also--double./f:nโ sets the maximum number of open files. See also--max-files./s:nโ sets the maximum record length forRANDOMfiles. See also--max-reclen./c:nโ sets the size of the receive buffer for COM devices. See also--serial-buffer-size./iโ statically allocate file control blocks and data buffer. Note that this is already the default approach in GW-BASIC and in PC-BASIC, so honestly this option has no effect. It's just here for the vibes (and compatibility)./m:n,mโ sets the highest memory location to n and maximum BASIC memory size to m*16 bytes. See also--max-memory.>filenameโ write screen output to filename. See also--output.>>filenameโ append screen output to filename. See also--output.<filenameโ read keyboard input from filename. See also--input.
GW-BASIC-style switches are not case sensitive, so go off. But real talk: the symbols used in these switches might mean something completely different in whatever shell you're calling PC-BASIC from, so you should quote and escape the options as necessary. The shell does not care about your feelings. ๐
โจ EXAMPLES โจ
pcbasicโ start PC-BASIC in direct mode, emulating GW-BASIC/BASICA with VGA graphics. The classic. The default. The moment.pcbasic --codepage=950โ start PC-BASIC using the Big-5 codepage.pcbasic Foobar.bazโ start PC-BASIC with packageFoobar. It loads the settings from the package, and usually that means it'll run a main program contained in the package.pcbasic Foobar.baz --convert=A --text-encoding=utf-8โ list the main program of packageFoobarto standard output as UTF-8.pcbasic MYPROG.BAS --mount=A:./files,B:./morefilesโ mount the current directory's subdirectoryfilesas driveA:and subdirectorymorefilesas driveB:, then runMYPROG.BAS.pcbasic --mount=A:C:\fakeflopโ run PC-BASIC with the Windows directoryC:\fakeflopmounted as theA:drive. Fake floppy, real vibes. ๐pcbasic Z:\INFO.BAS --preset=mda --monitor=amberโ runINFO.BASin the current directory on an emulated MDA with an amber tinted monitor. Aesthetic.pcbasic /home/me/retro/COMP.BAS --preset=cga --monitor=compositeโ runCOMP.BASstored at/home/me/retroon an emulated CGA machine with a composite monitor.pcbasic PCJRGAME.BAS --preset=pcjr -k='start\r'โ runPCJRGAME.BASon an emulated PCjr and feed in the keystrokes startEnter.pcbasic BANNER.BAS --lpt2=PRINTER:โ runBANNER.BASin default mode with the default printer attached toLPT2:.pcbasic --resumeโ resume the most recently closed PC-BASIC session. Your save file said "come back bestie" and you listened. ๐ซถpcbasic -c ?1+1โ execute the BASIC commandPRINT 1+1in the command-line interface and return to the calling shell.
๐ FILES ๐
$XDG_CONFIG_HOME/PCBASIC.INIor~/.config/pcbasic-2.0/PCBASIC.INIโ the user configuration file. Options in here look like command-line options but without the leading--. One option per line, okay? Options you put under the[pcbasic]header get loaded by default. Options under any other header get loaded if the--presetoption group of that name is loaded. It's giving very organized. ๐$XDG_DATA_HOME/pcbasic.sessionor~/.local/share/pcbasic-2.0/pcbasic.sessionโ the saved state of the last PC-BASIC session. Pick up where you left off with--resume. Heads up though: this file is saved in a binary storage format and is not meant to be edited or exchanged. Do not open it in a text editor and start typing, I'm begging. ๐
๐ ENVIRONMENT ๐
There are no environment settings specific to PC-BASIC. None. Zero. Nada. However โ and this is the fun part โ BASIC programs can still reach the environment through the ENVIRON$ function, so they could totally have their own environment settings going on. So it's not that the environment doesn't matter, it's just that it's not PC-BASIC's thing. Periodt.
๐ AUTHOR ๐
PC-BASIC is written and maintained by Rob Hagemans <rob.hagemans@hotmail.com>.
Show some love, they literally built an entire GW-BASIC emulator. Iconic behaviour. ๐๐
okay that's the whole page bestie, go forth and emulate ๐
โจ This was PCBASIC(1) โ yes, section 1 of the manual, the one and only โ and that little footer down at the bottom was just the man page signing its own name like the main character it is. ๐๐ฆ๐ธ
๐ฆ where this page comes from
- debian trixie: python3-pcbasic 2.0.7-7 ยท GPL-3.0-or-later
- ubuntu noble: python3-pcbasic 2.0.7-3 ยท GPL-3.0-or-later
- ubuntu questing: python3-pcbasic 2.0.7-7
- ubuntu resolute: python3-pcbasic 2.0.7-9 ยท GPL-3.0-or-later
- ubuntu stonking: python3-pcbasic 2.0.7-9 ยท GPL-3.0-or-later
- ๐ girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms