STRUCT V4L2_CTRL_HANDLER(9)

📦 version 7.3.1, in nixpkgs unstable

💖 struct v4l2_ctrl_handler(9) 💖

okay bestie, welcome to the Kernel API Manual — today we're reading the page for struct v4l2_ctrl_handler(9), and it's literally the main character of control bookkeeping. 🫶

🌸 NAME 🌸

struct v4l2_ctrl_handler — the control handler, and it keeps track of all the controls: both the controls owned by the handler and those inherited from other handlers. periodt 💅

✨ SYNOPSIS ✨

struct v4l2_ctrl_handler {
    struct mutex _lock;
    struct mutex *lock;
    struct list_head ctrls;
    struct list_head ctrl_refs;
    struct v4l2_ctrl_ref *cached;
    struct v4l2_ctrl_ref **buckets;
    v4l2_ctrl_notify_fnc notify;
    void *notify_priv;
    u16 nr_of_buckets;
    int error;
    bool request_is_queued;
    struct list_head requests;
    struct list_head requests_queued;
    struct media_request_object req_obj;
};

🎀 Members 🎀

  • _lock — the default for lock. 💖
  • lock — the lock that controls access to this handler and its controls. It may be replaced by the user right after init. 👀
  • ctrls — the list of controls owned by this handler. ✨
  • ctrl_refs — the list of control references. 🎀
  • cached — the last found control reference. It is common that the same control is needed multiple times, so this is a simple optimization. lowkey iconic. ⭐
  • buckets — buckets for the hashing. Allows for quick control lookup. 🔥
  • notify — a notify callback that is called whenever the control changes value. 🚨 Heads up: the handler's lock is held when the notify function is called!
  • notify_priv — passed as argument to the v4l2_ctrl notify callback. 🫶
  • nr_of_buckets — total number of buckets in the array. 🪣
  • error — the error code of the first failed control addition. 😭
  • request_is_queued — true if the request was queued. ✅
  • requests — list to keep track of open control handler request objects. For the parent control handler (req_obj.ops == NULL) this is the list header. When the parent control handler is removed, it has to unbind and put all these requests since they refer to the parent. 💀
  • requests_queued — list of the queued requests. This determines the order in which these controls are applied. Once the request is completed it is removed from this list. 🦋
  • req_obj — the struct media_request_object, used to link into a struct media_request. This request object has a refcount. 👑

💜 SEE ALSO 💜

Kernel file ./include/media/v4l2-ctrls.h — and the whole extended fam:

mwah 💋 — from ./include/media, October 2026, struct v4l2_ctrl_handler(9) — now go slay those controls, bestie! 💅✨

📦 where this page comes from