STRUCT V4L2_CTRL(9)

📦 version 7.3.1, in nixpkgs unstable

🎀 struct v4l2_ctrl(9) — The control structure 🎀

okay bestie, welcome to the Kernel API Manual page for struct v4l2_ctrl(9) 💅 this is the whole control-structure situation, and it’s lowkey iconic.

✨ NAME ✨

struct v4l2_ctrl — The control structure. 🫶

🌸 SYNOPSIS 🌸

so here’s the actual shape of struct v4l2_ctrl, and yes every field is exactly where it should be:

       struct v4l2_ctrl {
           struct list_head node;
           struct list_head ev_subs;
           struct v4l2_ctrl_handler *handler;
           struct v4l2_ctrl **cluster;
           unsigned int ncontrols;
           unsigned int done:1;
           unsigned int is_new:1;
           unsigned int has_changed:1;
           unsigned int is_private:1;
           unsigned int is_auto:1;
           unsigned int is_int:1;
           unsigned int is_string:1;
           unsigned int is_ptr:1;
           unsigned int is_array:1;
           unsigned int is_dyn_array:1;
           unsigned int has_volatiles:1;
           unsigned int call_notify:1;
           unsigned int manual_mode_value:8;
           const struct v4l2_ctrl_ops *ops;
           const struct v4l2_ctrl_type_ops *type_ops;
           u32 id;
           const char *name;
           enum v4l2_ctrl_type type;
           s64 minimum, maximum, default_value;
           u32 elems;
           u32 elem_size;
           u32 new_elems;
           u32 dims[V4L2_CTRL_MAX_DIMS];
           u32 nr_of_dims;
           union {
             u64 step;
             u64 menu_skip_mask;
           };
           union {
             const char * const *qmenu;
             const s64 *qmenu_int;
           };
           unsigned long flags;
           void *priv;
           void *p_array;
           u32 p_array_alloc_elems;
           s32 val;
           struct {
             s32 val;
           } cur;
           union v4l2_ctrl_ptr p_def;
           union v4l2_ctrl_ptr p_min;
           union v4l2_ctrl_ptr p_max;
           union v4l2_ctrl_ptr p_new;
           union v4l2_ctrl_ptr p_cur;
        };

🧚 Members 🧚

  • node — the list node. just vibing in the linked list 💫
  • ev_subs — the list of control event subscriptions 🎟️
  • handler — the handler that owns the control 👑
  • cluster — points to the start of the cluster array 🫂
  • ncontrols — number of controls in the cluster array 🔢
  • done — internal flag: set for each processed control 🫡
  • is_new — set when the user specified a new value for this control. It is also set when called from v4l2_ctrl_handler_setup. Drivers should never set this flag. ⚠️
  • has_changed — set when the current value differs from the new value. Drivers should never use this flag. 🚫
  • is_private — if set, then this control is private to its handler and it will not be added to any other handlers. Drivers can set this flag. 🔒
  • is_auto — if set, then this control selects whether the other cluster members are in 'automatic' mode or 'manual' mode. This is used for autogain/gain type clusters. Drivers should never set this flag directly. 🎛️
  • is_int — if set, then this control has a simple integer value (i.e. it uses ctrl->val). 🔢
  • is_string — if set, then this control has type V4L2_CTRL_TYPE_STRING. 🧵
  • is_ptr — if set, then this control is an array and/or has type >= V4L2_CTRL_COMPOUND_TYPES and/or has type V4L2_CTRL_TYPE_STRING. In other words, struct v4l2_ext_control uses field p to point to the data. 👉
  • is_array — if set, then this control contains an N-dimensional array. 🧊
  • is_dyn_array — if set, then this control contains a dynamically sized 1-dimensional array. If this is set, then is_array is also set. 🌊
  • has_volatiles — if set, then one or more members of the cluster are volatile. Drivers should never touch this flag. 🧨
  • call_notify — if set, then call the handler's notify function whenever the control's value changes. 📣
  • manual_mode_value — if the is_auto flag is set, then this is the value of the auto control that determines if that control is in manual mode. So if the value of the auto control equals this value, then the whole cluster is in manual mode. Drivers should never set this flag directly. 🕹️
  • ops — the control ops. 🛠️
  • type_ops — the control type ops. 🧰
  • id — the control ID. 🆔
  • name — the control name. 🏷️
  • type — the control type. 🧬
  • minimum — the control's minimum value. ⬇️
  • maximum — the control's maximum value. ⬆️
  • default_value — the control's default value. 🎯
  • elems — the number of elements in the N-dimensional array. 🧮
  • elem_size — the size in bytes of the control. 📏
  • new_elems — the number of elements in p_new. This is the same as elems, except for dynamic arrays. In that case it is in the range of 1 to p_array_alloc_elems. 🔁
  • dims — the size of each dimension. 📐
  • nr_of_dims — the number of dimensions in dims. 🔢
  • {unnamed_union} — anonymous. this is the union where step / menu_skip_mask live 🫥
  • step — the control's step value for non-menu controls. 👣
  • menu_skip_mask — the control's skip mask for menu controls. This makes it easy to skip menu items that are not valid. If bit X is set, then menu item X is skipped. Of course, this only works for menus with <= 32 menu items. There are no menus that come close to that number, so this is OK. Should we ever need more, then this will have to be extended to a u64 or a bit array. 🚫
  • {unnamed_union} — anonymous. this is the union where qmenu / qmenu_int live 🫥
  • qmenu — a const char * array for all menu items. Array entries that are empty strings ("") correspond to non-existing menu items (this is in addition to the menu_skip_mask above). The last entry must be NULL. Used only if the type is V4L2_CTRL_TYPE_MENU. 📋
  • qmenu_int — a 64-bit integer array for integer menu items. The size of array must be equal to the menu size, e. g.:
:math:`ceil(ac{maximum - minimum}{step}) + 1`

Used only if the type is V4L2_CTRL_TYPE_INTEGER_MENU. 🔢

  • flags — the control's flags. 🚩
  • priv — the control's private pointer. For use by the driver. It is untouched by the control framework. Note that this pointer is not freed when the control is deleted. Should this be needed then a new internal bitfield can be added to tell the framework to free this pointer. 🔐
  • p_array — pointer to the allocated array. Only valid if is_array is true. 🧷
  • p_array_alloc_elems — the number of elements in the allocated array for both the cur and new values. So p_array is actually sized for 2 * p_array_alloc_elems * elem_size. Only valid if is_array is true. 🧮
  • val — the control's new s32 value. 🆕
  • cur — structure to store the current value. 📦
  • cur.val — the control's current value, if the type is represented via a u32 integer (see enum v4l2_ctrl_type). 🎚️
  • p_def — the control's default value represented via a union which provides a standard way of accessing control types through a pointer (for compound controls only). 🎁
  • p_min — the control's minimum value represented via a union which provides a standard way of accessing control types through a pointer (for compound controls only). ⬇️
  • p_max — the control's maximum value represented via a union which provides a standard way of accessing control types through a pointer (for compound controls only). ⬆️
  • p_new — the control's new value represented via a union which provides a standard way of accessing control types through a pointer. 🆕
  • p_cur — the control's current value represented via a union which provides a standard way of accessing control types through a pointer. 🎯

🌈 SEE ALSO 🌈

okay that’s the whole page, bestie 🫶 source/version path: ./include/media, date: October 2026, and the page is struct v4l2_ctrl(9). mwah 💋

📦 where this page comes from