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.. _request-func-ioctl:
28
29***************
30request ioctl()
31***************
32
33Name
34====
35
36request-ioctl - Control a request file descriptor
37
38
39Synopsis
40========
41
42.. code-block:: c
43
44    #include <sys/ioctl.h>
45
46
47.. c:function:: int ioctl( int fd, int cmd, void *argp )
48    :name: req-ioctl
49
50Arguments
51=========
52
53``fd``
54    File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.
55
56``cmd``
57    The request ioctl command code as defined in the media.h header file, for
58    example :ref:`MEDIA_REQUEST_IOC_QUEUE`.
59
60``argp``
61    Pointer to a request-specific structure.
62
63
64Description
65===========
66
67The :ref:`ioctl() <request-func-ioctl>` function manipulates request
68parameters. The argument ``fd`` must be an open file descriptor.
69
70The ioctl ``cmd`` code specifies the request function to be called. It
71has encoded in it whether the argument is an input, output or read/write
72parameter, and the size of the argument ``argp`` in bytes.
73
74Macros and structures definitions specifying request ioctl commands and
75their parameters are located in the media.h header file. All request ioctl
76commands, their respective function and parameters are specified in
77:ref:`media-user-func`.
78
79
80Return Value
81============
82
83On success 0 is returned, on error -1 and the ``errno`` variable is set
84appropriately. The generic error codes are described at the
85:ref:`Generic Error Codes <gen-errors>` chapter.
86
87Command-specific error codes are listed in the individual command
88descriptions.
89
90When an ioctl that takes an output or read/write parameter fails, the
91parameter remains unmodified.
92