Skip to content
FreeDOSDeep Dive Published Updated 7 min readViews unavailable

DOS INT 21h AH=0Ch: Flush-Then-Read Input Semantics

Use DOS AH=0Ch to discard pending character input before a supported read, while respecting redirection, function selection, and FreeDOS behavior.

INT 21h function AH=0Ch combines an input-buffer flush with a selected input function. Its common use is to ensure that an application does not consume characters typed ahead before it asks a question. It is not a generic “clear every input source” operation, does not erase a redirected file, and does not replace the input function’s own contract.

The call places 0Ch in AH and the desired input function number in AL. The historical MS-DOS documentation lists 01h, 06h, 07h, 08h, and 0Ah as valid follow-up function numbers. With AL=0Ah, the caller also provides a buffered-input structure at DS:DX; with AL=06h for input, DL=FFh selects the input path. Other AL values perform the flush without a follow-up read in the documented contract.

; DS must address the application's data segment.
mov  ah, 0Ch
mov  al, 0Ah       ; flush pending input, then buffered line input
mov  dx, offset line_buffer
int  21h

The sample shows register setup only. The buffer format and size constraints belong to function 0Ah; use the buffer contract for the target DOS version and do not reuse a buffer from a different API. If AL=06h is selected, set DL=FFh for direct console input rather than assuming the default value already means “read.”

What is being flushed?

Historical DOS references describe AH=0Ch as clearing the standard-input buffer and then invoking another input service. On early systems, the type-ahead keyboard buffer is the intuitive case: a user presses keys while a program is busy, then the program later asks a yes/no question. A flush prevents already queued input from being treated as a new answer.

That language can be misleading when standard input is redirected. The MS-DOS Encyclopedia notes that with DOS 2.0 and later, if input is redirected from a file, function 0Ch does not empty the keyboard type-ahead buffer before it carries out the selected read. The redirected stream remains an input source; it is not truncated or reset to byte zero by a keyboard flush. FreeDOS’s kernel implementation obtains the standard-input device and calls its console flush routine only when standard input maps to a character device, then dispatches the supported input function. This implementation detail reinforces the need to distinguish console type-ahead from redirected data.

Do not promise that AH=0Ch drains a serial port, clears a pipe, discards an entire file, resets a network input stream, or flushes every device driver. The API is a DOS input function with a documented standard-input scope; behavior can depend on how the handle is attached and how a driver implements its device strategy. Test the exact console, redirection, or redirector path that the application uses.

Select the follow-up service intentionally

The AL value chooses which function runs after the flush. The historical references list:

  • 01h: character input with echo.
  • 06h: direct console I/O; DL=FFh requests input rather than output.
  • 07h: direct character input without echo.
  • 08h: character input without echo.
  • 0Ah: buffered line input through the caller’s buffer.

These functions are not interchangeable. Echo behavior, editing, redirection, and buffer requirements vary. For a password-like prompt, un-echoed input alone is not a complete secret-handling solution; typed data may remain in application memory, device buffers, or logs. For a line-oriented response, AH=0Ah requires correctly initialized buffer capacity. For a single key, choose a character service and handle extended-key conventions as documented for the target BIOS/DOS stack.

Invalid or unsupported AL values should not be treated as a successful read. Historical MS-DOS docs state that other values cause no further processing and return zero in AL. FreeDOS’s current kernel source switches only among the supported cases and otherwise returns after the flush path. Check flags and return values according to the chosen follow-up function, not merely the fact that INT 21h returned.

Redirection and testing boundaries

An input function may accept redirected input, so a call named “keyboard” can operate on standard input in a DOS 2+ environment. A batch or application launched with redirected input may therefore receive bytes from a file rather than fresh physical keystrokes. A program that assumes an interactive user is present can accidentally consume scripted data.

Build a small test program or controlled harness with four cases: direct console input with a key already queued; direct console input with no queued key; standard input redirected from a short file; and a character device or serial path if the product supports one. Record the result for each supported AL. Do not test by redirecting a production config file into a destructive application.

For redirected-input tests, preserve the fixture and inspect its contents before and after. The input file should remain unchanged by the read request itself, but file position advances as data is consumed. A subsequent open may start at a different position depending on handle lifecycle; AH=0Ch is not a seek-to-start function. Reopen or explicitly reposition the handle using the documented file API if that is required.

Pay attention to control-break and device-driver behavior as well. DOS input services may perform control-C checks according to their individual contracts, and a console driver may add editing or special-key processing. The flush function does not install a new handler, disable control-break globally, or guarantee that a hardware key pressed after the flush cannot be received. The correct mental model is “discard queued input the DOS path can flush, then invoke the selected reader,” not “lock input to future keystrokes forever.”

When a program is launched from a batch file, a redirected standard input may be part of the automation contract. A call to AH=0Ch can consume a character from that stream and shift subsequent reads; the effect can look like the next prompt was skipped. Include standard handles and redirections in launch diagnostics. A shell pipe in FreeCOM is simulated with temporary files, so if a pipeline interacts with an application that prompts, validate the exact command and lifecycle instead of assuming a live keyboard is still connected.

If the application needs a fresh interactive answer while another source is redirected, it should open or address the intended device explicitly through a documented mechanism and validate that choice. AH=0Ch alone cannot guarantee that standard input is the physical keyboard. Keep UI interaction separate from machine-readable input where possible, and fail clearly when the expected device is unavailable.

Common failure modes

One common error is leaving AL uninitialized. The kernel may flush but dispatch no intended input function. Another is setting AL=0Ah but passing a pointer with the wrong DS, which makes DOS write input into unrelated memory. A third is using AL=06h for a nonblocking output operation while expecting a read; direct console I/O uses DL to distinguish the input case.

Another mistake is assuming that a flush synchronizes with an asynchronous device. A hardware keyboard buffer, BIOS key queue, DOS standard-input handle, remote terminal, and application buffer are different layers. AH=0Ch can only affect the layer implemented by the DOS path it invokes. If stale keystrokes survive, identify which buffer contains them rather than calling AH=0Ch repeatedly.

Finally, do not confuse AH=0Ch with DOS function 0Dh disk reset or with a generic file-buffer flush. Similar hexadecimal numbers can obscure unrelated APIs. Label assembly constants by function and keep input and disk-maintenance code separate.

Acceptance criteria

Before shipping AH=0Ch code, verify the selected function number, all required registers, the data-segment pointer, echo behavior, redirected-input behavior, and error handling on each supported DOS kernel. Confirm that stale input is discarded only when the input source and driver actually expose a flushable console queue. Test the application both interactively and with the exact redirection mechanism used in deployment.

AH=0Ch is a compact convenience for a common interaction problem: input typed before a prompt should not necessarily become the answer to that prompt. Its guarantee is bounded by the underlying standard-input device and the selected input function. Treat it as a flush-then-dispatch API, not a universal input reset, and use explicit, tested behavior wherever automated or redirected input is possible.

Related:

Sources:

Comments