[deliverable/linux.git] / Documentation / linux_tv / media / v4l / vidioc-prepare-buf.rst

.. -*- coding: utf-8; mode: rst -*-

.. _VIDIOC_PREPARE_BUF:

************************
ioctl VIDIOC_PREPARE_BUF
************************

*man VIDIOC_PREPARE_BUF(2)*

Prepare a buffer for I/O


Synopsis
========

.. c:function:: int ioctl( int fd, int request, struct v4l2_buffer *argp )

Arguments
=========

``fd``
    File descriptor returned by :ref:`open() <func-open>`.

``request``
    VIDIOC_PREPARE_BUF

``argp``


Description
===========

Applications can optionally call the :ref:`VIDIOC_PREPARE_BUF` ioctl to
pass ownership of the buffer to the driver before actually enqueuing it,
using the :ref:`VIDIOC_QBUF` ioctl, and to prepare it for future I/O. Such
preparations may include cache invalidation or cleaning. Performing them
in advance saves time during the actual I/O. In case such cache
operations are not required, the application can use one of
``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE`` and
``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` flags to skip the respective step.

The :c:type:`struct v4l2_buffer` structure is specified in
:ref:`buffer`.


Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

EBUSY
    File I/O is in progress.

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.


.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------
Commit	Line	Data
5377d91f MH	1	.. -- coding: utf-8; mode: rst --
5377d91f MH	2
af4a4d0d	3	.. _VIDIOC_PREPARE_BUF:
5377d91f MH	4
	5	************************
	6	ioctl VIDIOC_PREPARE_BUF
	7	************************
	8
	9	man VIDIOC_PREPARE_BUF(2)
	10
	11	Prepare a buffer for I/O
	12
	13
	14	Synopsis
	15	========
	16
	17	.. c:function:: int ioctl( int fd, int request, struct v4l2_buffer *argp )
	18
	19	Arguments
	20	=========
	21
	22	``fd``
	23	File descriptor returned by :ref:`open() <func-open>`.
	24
	25	``request``
	26	VIDIOC_PREPARE_BUF
	27
	28	``argp``
	29
	30
	31	Description
	32	===========
	33
2212ff25	34	Applications can optionally call the :ref:`VIDIOC_PREPARE_BUF` ioctl to
5377d91f	35	pass ownership of the buffer to the driver before actually enqueuing it,
2212ff25	36	using the :ref:`VIDIOC_QBUF` ioctl, and to prepare it for future I/O. Such
5377d91f MH	37	preparations may include cache invalidation or cleaning. Performing them
	38	in advance saves time during the actual I/O. In case such cache
	39	operations are not required, the application can use one of
	40	``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE`` and
	41	``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` flags to skip the respective step.
	42
	43	The :c:type:`struct v4l2_buffer` structure is specified in
	44	:ref:`buffer`.
	45
	46
	47	Return Value
	48	============
	49
	50	On success 0 is returned, on error -1 and the ``errno`` variable is set
	51	appropriately. The generic error codes are described at the
	52	:ref:`Generic Error Codes <gen-errors>` chapter.
	53
	54	EBUSY
	55	File I/O is in progress.
	56
	57	EINVAL
	58	The buffer ``type`` is not supported, or the ``index`` is out of
	59	bounds, or no buffers have been allocated yet, or the ``userptr`` or
	60	``length`` are invalid.
	61
	62
	63	.. ------------------------------------------------------------------------------
	64	.. This file was automatically converted from DocBook-XML with the dbxml
	65	.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
	66	.. from the linux kernel, refer to:
	67	..
	68	.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
	69	.. ------------------------------------------------------------------------------