1.. This file is dual-licensed: you can use it either under the terms
2.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this
3.. dual licensing only applies to this file, and not this project as a
4.. whole.
5..
6.. a) This file is free software; you can redistribute it and/or
7..    modify it under the terms of the GNU General Public License as
8..    published by the Free Software Foundation version 2 of
9..    the License.
10..
11..    This file is distributed in the hope that it will be useful,
12..    but WITHOUT ANY WARRANTY; without even the implied warranty of
13..    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14..    GNU General Public License for more details.
15..
16.. Or, alternatively,
17..
18.. b) Permission is granted to copy, distribute and/or modify this
19..    document under the terms of the GNU Free Documentation License,
20..    Version 1.1 or any later version published by the Free Software
21..    Foundation, with no Invariant Sections, no Front-Cover Texts
22..    and no Back-Cover Texts. A copy of the license is included at
23..    Documentation/userspace-api/media/fdl-appendix.rst.
24..
25.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections
26
27.. _media_ioc_request_alloc:
28
29*****************************
30ioctl MEDIA_IOC_REQUEST_ALLOC
31*****************************
32
33Name
34====
35
36MEDIA_IOC_REQUEST_ALLOC - Allocate a request
37
38
39Synopsis
40========
41
42.. c:function:: int ioctl( int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp )
43    :name: MEDIA_IOC_REQUEST_ALLOC
44
45
46Arguments
47=========
48
49``fd``
50    File descriptor returned by :ref:`open() <media-func-open>`.
51
52``argp``
53    Pointer to an integer.
54
55
56Description
57===========
58
59If the media device supports :ref:`requests <media-request-api>`, then
60this ioctl can be used to allocate a request. If it is not supported, then
61``errno`` is set to ``ENOTTY``. A request is accessed through a file descriptor
62that is returned in ``*argp``.
63
64If the request was successfully allocated, then the request file descriptor
65can be passed to the :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
66:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
67:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and
68:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctls.
69
70In addition, the request can be queued by calling
71:ref:`MEDIA_REQUEST_IOC_QUEUE` and re-initialized by calling
72:ref:`MEDIA_REQUEST_IOC_REINIT`.
73
74Finally, the file descriptor can be :ref:`polled <request-func-poll>` to wait
75for the request to complete.
76
77The request will remain allocated until all the file descriptors associated
78with it are closed by :ref:`close() <request-func-close>` and the driver no
79longer uses the request internally. See also
80:ref:`here <media-request-life-time>` for more information.
81
82Return Value
83============
84
85On success 0 is returned, on error -1 and the ``errno`` variable is set
86appropriately. The generic error codes are described at the
87:ref:`Generic Error Codes <gen-errors>` chapter.
88
89ENOTTY
90    The driver has no support for requests.
91