framebuffer-dump 1 user commands nosh
framebuffer-dump dump the graphics mode contents of the framebuffer to a PBM, PGM, or PPM file
`framebuffer-dump` fbname

## Description

`framebuffer-dump` opens the framebuffer device named fbname and dumps its contents as a Portable Bitmap (PBM), a Portable Grayscale (PGM), or a Portable Pixmap (PPM) file to its standard output. The output is suitable for input straight in to many netpbm tools, such as (for one example) the pbmtojpeg 1 utility.

On Linux framebuffer device filenames take the form `/dev/fbnumber`. On FreeBSD framebuffer device filenames take the form `/dev/ttyvhexnumber`. On NetBSD framebuffer device filenames take the form `/dev/tty[EF]number`.

Only graphic modes can be dumped; text modes cannot be. Of those graphic modes, only linear or "packed pixel" modes can be dumped. i.e. `framebuffer-dump` will not attempt to dump the framebuffer if vidcontrol 8 has set an old "planar" VGA mode.

Most Super VGA cards (sic!) are capable of a linear mode equivalent to the old "planar" VGA mode, with the same resolution, and those modes should be used instead. As a beneficial side-effect, dropping use of the "planar" video modes allows other softwares that use framebuffers to take a code path where they no longer require direct I/O instruction access to the display hardware from application mode, and no longer require superuser privileges, just read+write access to the framebuffer device.

In Direct Colour modes, the framebuffer contents are output as a PPM file. In Indexed Colour (i.e. palette colour) modes, the framebuffer contents are output as a PPM file, mapping the colours to RGB values using the same (default) palette as used by console-terminal-emulator 1. In Monochrome modes, the framebuffer contents are output as PBM file. All three use the relevant textual "plain" file format rather than the binary "raw" format.

Strictly speaking the stock FreeBSD vga 4 framebuffer driver in FreeBSD is capable of Monochome modes. But they are supplanted by vesa 4 which usually does not advertise any.
32-bit TrueColour, 24-bit TrueColour, 16-bit, and 15-bit modes are all Direct Colour systems. They all store RGB values directly in the framebuffer memory.

## Security

The ability to dump the framebuffer is the ability to see whatever a user using that framebuffer is doing.

For this reason, FreeBSD does not permit access to the framebuffer unless the `/dev/ttyvnumber` device is the currently active kernel virtual terminal being rendered upon it. Otherwise, since logged-in users have owner access to their kernel virtual terminals, one logged-in user could see the framebuffer of another logged-in user's virtual terminal. The obscure error that it returns to indicate that the framebuffer is not the active kernel virtual terminal device is "Invalid parameter".

The currently active kernel virtual terminal can be set by hotkeys or with the console-multiplexor-control 1 utility. See syscons 4 and vt 4.

## History

Early development versions of this utility output Indexed Colour as a PGM file. This proved to be not useful.

## Author

Jonathan de Boyne Pollard