Home | History | Annotate | Download | only in spec
      1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
      2 <HTML
      3 ><HEAD
      4 ><TITLE
      5 >V4L2 ioctl()</TITLE
      6 ><META
      7 NAME="GENERATOR"
      8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
      9 REL="HOME"
     10 TITLE="Video for Linux Two API Specification"
     11 HREF="book1.htm"><LINK
     12 REL="UP"
     13 TITLE="Function Reference"
     14 HREF="r7624.htm"><LINK
     15 REL="PREVIOUS"
     16 TITLE="V4L2 close()"
     17 HREF="r7626.htm"><LINK
     18 REL="NEXT"
     19 TITLE="ioctl VIDIOC_CROPCAP"
     20 HREF="r7771.htm"></HEAD
     21 ><BODY
     22 CLASS="REFENTRY"
     23 BGCOLOR="#FFFFFF"
     24 TEXT="#000000"
     25 LINK="#0000FF"
     26 VLINK="#840084"
     27 ALINK="#0000FF"
     28 ><DIV
     29 CLASS="NAVHEADER"
     30 ><TABLE
     31 SUMMARY="Header navigation table"
     32 WIDTH="100%"
     33 BORDER="0"
     34 CELLPADDING="0"
     35 CELLSPACING="0"
     36 ><TR
     37 ><TH
     38 COLSPAN="3"
     39 ALIGN="center"
     40 >Video for Linux Two API Specification: Revision 0.24</TH
     41 ></TR
     42 ><TR
     43 ><TD
     44 WIDTH="10%"
     45 ALIGN="left"
     46 VALIGN="bottom"
     47 ><A
     48 HREF="r7626.htm"
     49 ACCESSKEY="P"
     50 >Prev</A
     51 ></TD
     52 ><TD
     53 WIDTH="80%"
     54 ALIGN="center"
     55 VALIGN="bottom"
     56 ></TD
     57 ><TD
     58 WIDTH="10%"
     59 ALIGN="right"
     60 VALIGN="bottom"
     61 ><A
     62 HREF="r7771.htm"
     63 ACCESSKEY="N"
     64 >Next</A
     65 ></TD
     66 ></TR
     67 ></TABLE
     68 ><HR
     69 ALIGN="LEFT"
     70 WIDTH="100%"></DIV
     71 ><H1
     72 ><A
     73 NAME="FUNC-IOCTL"
     74 ></A
     75 >V4L2 ioctl()</H1
     76 ><DIV
     77 CLASS="REFNAMEDIV"
     78 ><A
     79 NAME="AEN7671"
     80 ></A
     81 ><H2
     82 >Name</H2
     83 >v4l2-ioctl&nbsp;--&nbsp;Program a V4L2 device</DIV
     84 ><DIV
     85 CLASS="REFSYNOPSISDIV"
     86 ><A
     87 NAME="AEN7674"
     88 ></A
     89 ><H2
     90 >Synopsis</H2
     91 ><DIV
     92 CLASS="FUNCSYNOPSIS"
     93 ><P
     94 ></P
     95 ><A
     96 NAME="AEN7675"
     97 ></A
     98 ><PRE
     99 CLASS="FUNCSYNOPSISINFO"
    100 >#include &lt;sys/ioctl.h&gt;</PRE
    101 ><P
    102 ><CODE
    103 ><CODE
    104 CLASS="FUNCDEF"
    105 >int ioctl</CODE
    106 >(int fd, int request, void *argp);</CODE
    107 ></P
    108 ><P
    109 ></P
    110 ></DIV
    111 ></DIV
    112 ><DIV
    113 CLASS="REFSECT1"
    114 ><A
    115 NAME="AEN7686"
    116 ></A
    117 ><H2
    118 >Arguments</H2
    119 ><P
    120 ></P
    121 ><DIV
    122 CLASS="VARIABLELIST"
    123 ><DL
    124 ><DT
    125 ><CODE
    126 CLASS="PARAMETER"
    127 >fd</CODE
    128 ></DT
    129 ><DD
    130 ><P
    131 >File descriptor returned by <A
    132 HREF="r14090.htm"
    133 ><CODE
    134 CLASS="FUNCTION"
    135 >open()</CODE
    136 ></A
    137 >.</P
    138 ></DD
    139 ><DT
    140 ><CODE
    141 CLASS="PARAMETER"
    142 >request</CODE
    143 ></DT
    144 ><DD
    145 ><P
    146 >V4L2 ioctl request code as defined in the <A
    147 HREF="a16506.htm"
    148 >videodev.h</A
    149 > header file, for example
    150 VIDIOC_QUERYCAP.</P
    151 ></DD
    152 ><DT
    153 ><CODE
    154 CLASS="PARAMETER"
    155 >argp</CODE
    156 ></DT
    157 ><DD
    158 ><P
    159 >Pointer to a function parameter, usually a structure.</P
    160 ></DD
    161 ></DL
    162 ></DIV
    163 ></DIV
    164 ><DIV
    165 CLASS="REFSECT1"
    166 ><A
    167 NAME="AEN7707"
    168 ></A
    169 ><H2
    170 >Description</H2
    171 ><P
    172 >The <CODE
    173 CLASS="FUNCTION"
    174 >ioctl()</CODE
    175 > function is used to program
    176 V4L2 devices. The argument <CODE
    177 CLASS="PARAMETER"
    178 >fd</CODE
    179 > must be an open
    180 file descriptor. An ioctl <CODE
    181 CLASS="PARAMETER"
    182 >request</CODE
    183 > has encoded
    184 in it whether the argument is an input, output or read/write
    185 parameter, and the size of the argument <CODE
    186 CLASS="PARAMETER"
    187 >argp</CODE
    188 > in
    189 bytes. Macros and defines specifying V4L2 ioctl requests are located
    190 in the <A
    191 HREF="a16506.htm"
    192 >videodev.h</A
    193 > header file.
    194 Applications should use their own copy, not include the version in the
    195 kernel sources on the system they compile on. All V4L2 ioctl requests,
    196 their respective function and parameters are specified in <A
    197 HREF="r7624.htm"
    198 >Reference I, <I
    199 >Function Reference</I
    200 ></A
    201 >.</P
    202 ></DIV
    203 ><DIV
    204 CLASS="REFSECT1"
    205 ><A
    206 NAME="AEN7716"
    207 ></A
    208 ><H2
    209 >Return Value</H2
    210 ><P
    211 >On success the <CODE
    212 CLASS="FUNCTION"
    213 >ioctl()</CODE
    214 > function returns
    215 <SPAN
    216 CLASS="RETURNVALUE"
    217 >0</SPAN
    218 > and does not reset the
    219 <CODE
    220 CLASS="VARNAME"
    221 >errno</CODE
    222 > variable. On failure
    223 <SPAN
    224 CLASS="RETURNVALUE"
    225 >-1</SPAN
    226 > is returned, when the ioctl takes an
    227 output or read/write parameter it remains unmodified, and the
    228 <CODE
    229 CLASS="VARNAME"
    230 >errno</CODE
    231 > variable is set appropriately. See below for
    232 possible error codes. Generic errors like <SPAN
    233 CLASS="ERRORCODE"
    234 >EBADF</SPAN
    235 >
    236 or <SPAN
    237 CLASS="ERRORCODE"
    238 >EFAULT</SPAN
    239 > are not listed in the sections
    240 discussing individual ioctl requests.</P
    241 ><P
    242 >Note ioctls may return undefined error codes. Since errors
    243 may have side effects such as a driver reset applications should
    244 abort on unexpected errors.</P
    245 ><P
    246 ></P
    247 ><DIV
    248 CLASS="VARIABLELIST"
    249 ><DL
    250 ><DT
    251 ><SPAN
    252 CLASS="ERRORCODE"
    253 >EBADF</SPAN
    254 ></DT
    255 ><DD
    256 ><P
    257 ><CODE
    258 CLASS="PARAMETER"
    259 >fd</CODE
    260 > is not a valid open file
    261 descriptor.</P
    262 ></DD
    263 ><DT
    264 ><SPAN
    265 CLASS="ERRORCODE"
    266 >EBUSY</SPAN
    267 ></DT
    268 ><DD
    269 ><P
    270 >The property cannot be changed right now. Typically
    271 this error code is returned when I/O is in progress or the driver
    272 supports multiple opens and another process locked the property.</P
    273 ></DD
    274 ><DT
    275 ><SPAN
    276 CLASS="ERRORCODE"
    277 >EFAULT</SPAN
    278 ></DT
    279 ><DD
    280 ><P
    281 ><CODE
    282 CLASS="PARAMETER"
    283 >argp</CODE
    284 > references an inaccessible
    285 memory area.</P
    286 ></DD
    287 ><DT
    288 ><SPAN
    289 CLASS="ERRORCODE"
    290 >ENOTTY</SPAN
    291 ></DT
    292 ><DD
    293 ><P
    294 ><CODE
    295 CLASS="PARAMETER"
    296 >fd</CODE
    297 > is  not  associated  with  a
    298 character special device.</P
    299 ></DD
    300 ><DT
    301 ><SPAN
    302 CLASS="ERRORCODE"
    303 >EINVAL</SPAN
    304 ></DT
    305 ><DD
    306 ><P
    307 >The <CODE
    308 CLASS="PARAMETER"
    309 >request</CODE
    310 > or the data pointed
    311 to by <CODE
    312 CLASS="PARAMETER"
    313 >argp</CODE
    314 > is not valid. This is a very common
    315 error code, see the individual ioctl requests listed in <A
    316 HREF="r7624.htm"
    317 >Reference I, <I
    318 >Function Reference</I
    319 ></A
    320 > for actual causes.</P
    321 ></DD
    322 ><DT
    323 ><SPAN
    324 CLASS="ERRORCODE"
    325 >ENOMEM</SPAN
    326 ></DT
    327 ><DD
    328 ><P
    329 >Not enough physical or virtual memory was available to
    330 complete the request.</P
    331 ></DD
    332 ><DT
    333 ><SPAN
    334 CLASS="ERRORCODE"
    335 >ERANGE</SPAN
    336 ></DT
    337 ><DD
    338 ><P
    339 >The application attempted to set a control with the
    340 <A
    341 HREF="r10104.htm"
    342 ><CODE
    343 CLASS="CONSTANT"
    344 >VIDIOC_S_CTRL</CODE
    345 ></A
    346 > ioctl to a value which is out of bounds.</P
    347 ></DD
    348 ></DL
    349 ></DIV
    350 ></DIV
    351 ><DIV
    352 CLASS="NAVFOOTER"
    353 ><HR
    354 ALIGN="LEFT"
    355 WIDTH="100%"><TABLE
    356 SUMMARY="Footer navigation table"
    357 WIDTH="100%"
    358 BORDER="0"
    359 CELLPADDING="0"
    360 CELLSPACING="0"
    361 ><TR
    362 ><TD
    363 WIDTH="33%"
    364 ALIGN="left"
    365 VALIGN="top"
    366 ><A
    367 HREF="r7626.htm"
    368 ACCESSKEY="P"
    369 >Prev</A
    370 ></TD
    371 ><TD
    372 WIDTH="34%"
    373 ALIGN="center"
    374 VALIGN="top"
    375 ><A
    376 HREF="book1.htm"
    377 ACCESSKEY="H"
    378 >Home</A
    379 ></TD
    380 ><TD
    381 WIDTH="33%"
    382 ALIGN="right"
    383 VALIGN="top"
    384 ><A
    385 HREF="r7771.htm"
    386 ACCESSKEY="N"
    387 >Next</A
    388 ></TD
    389 ></TR
    390 ><TR
    391 ><TD
    392 WIDTH="33%"
    393 ALIGN="left"
    394 VALIGN="top"
    395 >V4L2 close()</TD
    396 ><TD
    397 WIDTH="34%"
    398 ALIGN="center"
    399 VALIGN="top"
    400 ><A
    401 HREF="r7624.htm"
    402 ACCESSKEY="U"
    403 >Up</A
    404 ></TD
    405 ><TD
    406 WIDTH="33%"
    407 ALIGN="right"
    408 VALIGN="top"
    409 >ioctl VIDIOC_CROPCAP</TD
    410 ></TR
    411 ></TABLE
    412 ></DIV
    413 ></BODY
    414 ></HTML
    415 >
    416