0001 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: MC
0003
0004 .. _media_ioc_request_alloc:
0005
0006 *****************************
0007 ioctl MEDIA_IOC_REQUEST_ALLOC
0008 *****************************
0009
0010 Name
0011 ====
0012
0013 MEDIA_IOC_REQUEST_ALLOC - Allocate a request
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: MEDIA_IOC_REQUEST_ALLOC
0019
0020 ``int ioctl(int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp)``
0021
0022 Arguments
0023 =========
0024
0025 ``fd``
0026 File descriptor returned by :c:func:`open()`.
0027
0028 ``argp``
0029 Pointer to an integer.
0030
0031 Description
0032 ===========
0033
0034 If the media device supports :ref:`requests <media-request-api>`, then
0035 this ioctl can be used to allocate a request. If it is not supported, then
0036 ``errno`` is set to ``ENOTTY``. A request is accessed through a file descriptor
0037 that is returned in ``*argp``.
0038
0039 If the request was successfully allocated, then the request file descriptor
0040 can be passed to the :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
0041 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
0042 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and
0043 :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctls.
0044
0045 In addition, the request can be queued by calling
0046 :ref:`MEDIA_REQUEST_IOC_QUEUE` and re-initialized by calling
0047 :ref:`MEDIA_REQUEST_IOC_REINIT`.
0048
0049 Finally, the file descriptor can be :ref:`polled <request-func-poll>` to wait
0050 for the request to complete.
0051
0052 The request will remain allocated until all the file descriptors associated
0053 with it are closed by :c:func:`close()` and the driver no
0054 longer uses the request internally. See also
0055 :ref:`here <media-request-life-time>` for more information.
0056
0057 Return Value
0058 ============
0059
0060 On success 0 is returned, on error -1 and the ``errno`` variable is set
0061 appropriately. The generic error codes are described at the
0062 :ref:`Generic Error Codes <gen-errors>` chapter.
0063
0064 ENOTTY
0065 The driver has no support for requests.
