setmetamode

setmetamode [framebuffer] mode

framebuffer
    The framebuffer device to configure. Usually something like '/dev/fb0' or '/dev/fb1'. If omitted, applies to all framebuffers.

mode
    The video mode to set. This is specified in the format 'widthxheight[-depth][@refresh]'. For example, '1024x768-16@60' sets a resolution of 1024x768 with a color depth of 16 bits and a refresh rate of 60 Hz.

The setmetamode command is used to configure the video mode for specific framebuffers on a Linux system. It provides a way to specify the display resolution, refresh rate, and other related parameters directly to the kernel's framebuffer driver. This is useful for controlling how the display appears, especially when the graphical environment is not running or doesn't have the capability to configure the video mode correctly.
It is used in scripts or initialization processes when a very specific and consistent display setup is needed, and when the higher-level tools might not provide the needed functionality or control.
setmetamode allows a fine level of configuration. Without arguments, setmetamode returns the display sizes of all configured framebuffers.

Setting an unsupported mode can result in a blank screen or distorted display. Be cautious when specifying modes. Incorrect parameters might cause the system to crash.

The mode parameter follows a specific format. 'width' is the horizontal resolution in pixels, 'height' is the vertical resolution in pixels, 'depth' is the color depth in bits (e.g., 8, 16, 24, 32), and 'refresh' is the refresh rate in Hertz. The depth and refresh rate are optional.

It is important to consider implementing error handling when using setmetamode. The command does not always exit with an error code when the specified mode is invalid. Checking if the display functions as expected after executing the command is recommended.

fbset(1), vbetool(1)