console-multiplexor — realize many user-space virtual terminals on one


console-multiplexor [--display-only] {muxname} {vcname...}


console-multiplexor multiplexes one or more (user-space) virtual terminals onto a single (user-space) virtual terminal, acting as a realizer for the former.

It opens the character/attribute buffer file(s) vcname/display and the input FIFO(s) vcname/input. These are the back-end interfaces of the user-space virtual terminal(s) being multiplexed, as detailed in console-terminal-emulator(1). It does not attempt to create these if they do not exist.

It opens the character/attribute buffer file muxname/display and the input FIFO muxname/input. These are the back-end interfaces of the single user-space virtual terminal onto which the others are multiplexed. It will create these if they do not exist. They have their group IDs explicitly set to the effective GID of the multiplexor process.

It then enters a loop where it simultaneously:

  • (unless the --display-only option is used) writes all data received from the mux input FIFO to the input FIFO for the foreground virtual terminal; and

  • renders the contents of the character/attribute buffer file for the foreground virtual terminal on the mux virtual terminal's display buffer.

One virtual terminal is in the foreground. This is the virtual terminal that is currently rendered onto the mux display buffer and to which input events are sent. It is changed in response to special session switch input events, generated by whatever realizer is attached to the mux virtual terminal; and key events for the Next Task, Previous Task, and Task Selection Consumer keypad keys. These events are filtered from the input stream and not passed along to the multiplexed virtual terminals. (The multiplexor also consumes other Consumer keys such as Terminal Lock, Log In, Log Out, Task Manager, and Halt Task. These are reserved for future use.)

The session switch event extension to the console-terminal-emulator(1) input protocol is


A session switch request. The session number is nnnn and mm is a set of bitflags indicating the current state of modifier keys. Sessions are numbered from 0, as per the FreeBSD and NetBSD console conventions.

Because of the modular nature of user space virtual terminals, there is no notion of an "active" virtual terminal that is visible to the programs that are running on the virtual terminals. Multiple multiplexers and realizers may be attached to the back end of any given virtual terminal; or indeed none may be attached at all. Session switching is commanded by realizers, exacted by multiplexors; and the terminal emulators have no hand in it.


console-multiplexor requires no superuser privileges and is designed to be run entirely under the aegis of a dedicated unprivileged user account. It only requires write and search access to muxname/ and need not have owner access to it.

Usually muxname/ will be set-group-ID to a group different to the effective group ID of the multiplexor process. Changing the groups of muxname/input, muxname/display to the effective group ID of the emulator process thus distinguishes group access to those files, allowing one to add ordinary users to that group in order to give them direct realizer access to the emulated terminal.


Jonathan de Boyne Pollard