Video for Linux Two API Specification: Revision 0.24
Prev |  | Next

# ioctl VIDIOC_QBUF, VIDIOC_DQBUF

## Name

VIDIOC_QBUF, VIDIOC_DQBUF -- Exchange a buffer with the driver

## Synopsis

``int ioctl`(int fd, int request, struct v4l2_buffer *argp);`

## Arguments

`fd`

  File descriptor returned by `open()`.

`request`

  VIDIOC_QBUF, VIDIOC_DQBUF

`argp`

## Description

Applications call the `VIDIOC_QBUF` ioctl to enqueue an empty (capturing) or filled (output) buffer in the driver's incoming queue. The semantics depend on the selected I/O method.

To enqueue a memory mapped buffer applications set the `type` field of a struct v4l2_buffer to the same buffer type as previously struct v4l2_format `type` and struct v4l2_requestbuffers `type`, the `memory` field to `V4L2_MEMORY_MMAP` and the `index` field. Valid index numbers range from zero to the number of buffers allocated with `VIDIOC_REQBUFS` (struct v4l2_requestbuffers `count`) minus one. The contents of the struct `v4l2_buffer` returned by a `VIDIOC_QUERYBUF` ioctl will do as well. When the buffer is intended for output (`type` is `V4L2_BUF_TYPE_VIDEO_OUTPUT` or `V4L2_BUF_TYPE_VBI_OUTPUT`) applications must also initialize the `bytesused`, `field` and `timestamp` fields. See Section 3.5 for details. When `VIDIOC_QBUF` is called with a pointer to this structure the driver sets the `V4L2_BUF_FLAG_MAPPED` and `V4L2_BUF_FLAG_QUEUED` flags and clears the `V4L2_BUF_FLAG_DONE` flag in the `flags` field, or it returns an EINVAL error code.

To enqueue a user pointer buffer applications set the `type` field of a struct v4l2_buffer to the same buffer type as previously struct v4l2_format `type` and struct v4l2_requestbuffers `type`, the `memory` field to `V4L2_MEMORY_USERPTR` and the `m.userptr` field to the address of the buffer and `length` to its size. When the buffer is intended for output additional fields must be set as above. When `VIDIOC_QBUF` is called with a pointer to this structure the driver sets the `V4L2_BUF_FLAG_QUEUED` flag and clears the `V4L2_BUF_FLAG_MAPPED` and `V4L2_BUF_FLAG_DONE` flags in the `flags` field, or it returns an error code. This ioctl locks the memory pages of the buffer in physical memory, they cannot be swapped out to disk. Buffers remain locked until dequeued, until the `VIDIOC_STREAMOFF` or `VIDIOC_REQBUFS` ioctl are called, or until the device is closed.

Applications call the `VIDIOC_DQBUF` ioctl to dequeue a filled (capturing) or displayed (output) buffer from the driver's outgoing queue. They just set the `type` and `memory` fields of a struct v4l2_buffer as above, when `VIDIOC_DQBUF` is called with a pointer to this structure the driver fills the remaining fields or returns an error code.

By default `VIDIOC_DQBUF` blocks when no buffer is in the outgoing queue. When the `O_NONBLOCK` flag was given to the `open()` function, `VIDIOC_DQBUF` returns immediately with an EAGAIN error code when no buffer is available.

The `v4l2_buffer` structure is specified in Section 3.5.

## Return Value

On success 0 is returned, on error -1 and the `errno` variable is set appropriately:

EAGAIN

  Non-blocking I/O has been selected using `O_NONBLOCK` and no buffer was in the outgoing queue.

EINVAL

  The buffer `type` is not supported, or the `index` is out of bounds, or no buffers have been allocated yet, or the `userptr` or `length` are invalid.

ENOMEM

  Not enough physical or virtual memory was available to enqueue a user pointer buffer.

EIO

  `VIDIOC_DQBUF` failed due to an internal error. Can also indicate temporary problems like signal loss. Note the driver might dequeue an (empty) buffer despite returning an error, or even stop capturing.

Prev | Home | Next
ioctl VIDIOC_OVERLAY | Up | ioctl VIDIOC_QUERYBUF