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>ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, 6VIDIOC_TRY_EXT_CTRLS</TITLE 7><META 8NAME="GENERATOR" 9CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK 10REL="HOME" 11TITLE="Video for Linux Two API Specification" 12HREF="book1.htm"><LINK 13REL="UP" 14TITLE="Function Reference" 15HREF="r7624.htm"><LINK 16REL="PREVIOUS" 17TITLE="ioctl VIDIOC_G_ENC_INDEX" 18HREF="r10211.htm"><LINK 19REL="NEXT" 20TITLE="ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF" 21HREF="r10595.htm"></HEAD 22><BODY 23CLASS="REFENTRY" 24BGCOLOR="#FFFFFF" 25TEXT="#000000" 26LINK="#0000FF" 27VLINK="#840084" 28ALINK="#0000FF" 29><DIV 30CLASS="NAVHEADER" 31><TABLE 32SUMMARY="Header navigation table" 33WIDTH="100%" 34BORDER="0" 35CELLPADDING="0" 36CELLSPACING="0" 37><TR 38><TH 39COLSPAN="3" 40ALIGN="center" 41>Video for Linux Two API Specification: Revision 0.24</TH 42></TR 43><TR 44><TD 45WIDTH="10%" 46ALIGN="left" 47VALIGN="bottom" 48><A 49HREF="r10211.htm" 50ACCESSKEY="P" 51>Prev</A 52></TD 53><TD 54WIDTH="80%" 55ALIGN="center" 56VALIGN="bottom" 57></TD 58><TD 59WIDTH="10%" 60ALIGN="right" 61VALIGN="bottom" 62><A 63HREF="r10595.htm" 64ACCESSKEY="N" 65>Next</A 66></TD 67></TR 68></TABLE 69><HR 70ALIGN="LEFT" 71WIDTH="100%"></DIV 72><H1 73><A 74NAME="VIDIOC-G-EXT-CTRLS" 75></A 76>ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, 77VIDIOC_TRY_EXT_CTRLS</H1 78><DIV 79CLASS="REFNAMEDIV" 80><A 81NAME="AEN10390" 82></A 83><H2 84>Name</H2 85>VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, VIDIOC_TRY_EXT_CTRLS -- Get or set the value of several controls, try control 86values</DIV 87><DIV 88CLASS="REFSYNOPSISDIV" 89><A 90NAME="AEN10395" 91></A 92><H2 93>Synopsis</H2 94><DIV 95CLASS="FUNCSYNOPSIS" 96><P 97></P 98><A 99NAME="AEN10396" 100></A 101><P 102><CODE 103><CODE 104CLASS="FUNCDEF" 105>int ioctl</CODE 106>(int fd, int request, struct v4l2_ext_controls 107*argp);</CODE 108></P 109><P 110></P 111></DIV 112></DIV 113><DIV 114CLASS="REFSECT1" 115><A 116NAME="AEN10406" 117></A 118><H2 119>Arguments</H2 120><P 121></P 122><DIV 123CLASS="VARIABLELIST" 124><DL 125><DT 126><CODE 127CLASS="PARAMETER" 128>fd</CODE 129></DT 130><DD 131><P 132>File descriptor returned by <A 133HREF="r14090.htm" 134><CODE 135CLASS="FUNCTION" 136>open()</CODE 137></A 138>.</P 139></DD 140><DT 141><CODE 142CLASS="PARAMETER" 143>request</CODE 144></DT 145><DD 146><P 147>VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, 148VIDIOC_TRY_EXT_CTRLS</P 149></DD 150><DT 151><CODE 152CLASS="PARAMETER" 153>argp</CODE 154></DT 155><DD 156><P 157></P 158></DD 159></DL 160></DIV 161></DIV 162><DIV 163CLASS="REFSECT1" 164><A 165NAME="AEN10426" 166></A 167><H2 168>Description</H2 169><P 170>These ioctls allow the caller to get or set multiple 171controls atomically. Control IDs are grouped into control classes (see 172<A 173HREF="r10386.htm#CTRL-CLASS" 174>Table 3</A 175>) and all controls in the control array 176must belong to the same control class.</P 177><P 178>Applications must always fill in the 179<CODE 180CLASS="STRUCTFIELD" 181>count</CODE 182>, 183<CODE 184CLASS="STRUCTFIELD" 185>ctrl_class</CODE 186>, 187<CODE 188CLASS="STRUCTFIELD" 189>controls</CODE 190> and 191<CODE 192CLASS="STRUCTFIELD" 193>reserved</CODE 194> fields of struct <A 195HREF="r10386.htm#V4L2-EXT-CONTROLS" 196>v4l2_ext_controls</A 197>, and 198initialize the struct <A 199HREF="r10386.htm#V4L2-EXT-CONTROL" 200>v4l2_ext_control</A 201> array pointed to by the 202<CODE 203CLASS="STRUCTFIELD" 204>controls</CODE 205> fields.</P 206><P 207>To get the current value of a set of controls applications 208initialize the <CODE 209CLASS="STRUCTFIELD" 210>id</CODE 211> field of each 212struct <A 213HREF="r10386.htm#V4L2-EXT-CONTROL" 214>v4l2_ext_control</A 215> and call the 216<CODE 217CLASS="CONSTANT" 218>VIDIOC_G_EXT_CTRLS</CODE 219> ioctl.</P 220><P 221>To change the value of a set of controls applications 222initialize the <CODE 223CLASS="STRUCTFIELD" 224>id</CODE 225> and 226<CODE 227CLASS="STRUCTFIELD" 228>value</CODE 229> fields of a struct <A 230HREF="r10386.htm#V4L2-EXT-CONTROL" 231>v4l2_ext_control</A 232> and 233call the <CODE 234CLASS="CONSTANT" 235>VIDIOC_S_EXT_CTRLS</CODE 236> ioctl. The controls 237will only be set if <SPAN 238CLASS="emphasis" 239><I 240CLASS="EMPHASIS" 241>all</I 242></SPAN 243> control values are 244valid.</P 245><P 246>To check if the a set of controls have correct values 247applications initialize the <CODE 248CLASS="STRUCTFIELD" 249>id</CODE 250> and 251<CODE 252CLASS="STRUCTFIELD" 253>value</CODE 254> fields of a struct <A 255HREF="r10386.htm#V4L2-EXT-CONTROL" 256>v4l2_ext_control</A 257> and 258call the <CODE 259CLASS="CONSTANT" 260>VIDIOC_TRY_EXT_CTRLS</CODE 261> ioctl. It is up to 262the driver whether wrong values are automatically adjusted to a valid 263value or if an error is returned.</P 264><P 265>When the <CODE 266CLASS="STRUCTFIELD" 267>id</CODE 268> or 269<CODE 270CLASS="STRUCTFIELD" 271>ctrl_class</CODE 272> is invalid drivers return an 273<SPAN 274CLASS="ERRORCODE" 275>EINVAL</SPAN 276> error code. When the value is out of bounds drivers can choose to take 277the closest valid value or return an <SPAN 278CLASS="ERRORCODE" 279>ERANGE</SPAN 280> error code, whatever seems more 281appropriate. In the first case the new value is set in 282struct <A 283HREF="r10386.htm#V4L2-EXT-CONTROL" 284>v4l2_ext_control</A 285>.</P 286><P 287>The driver will only set/get these controls if all control 288values are correct. This prevents the situation where only some of the 289controls were set/get. Only low-level errors (e. g. a failed i2c 290command) can still cause this situation.</P 291><DIV 292CLASS="TABLE" 293><A 294NAME="V4L2-EXT-CONTROL" 295></A 296><P 297><B 298>Table 1. struct <CODE 299CLASS="STRUCTNAME" 300>v4l2_ext_control</CODE 301></B 302></P 303><TABLE 304BORDER="0" 305FRAME="void" 306WIDTH="100%" 307CLASS="CALSTABLE" 308><COL 309WIDTH="20%" 310TITLE="C1"><COL 311WIDTH="20%" 312TITLE="C2"><COL 313WIDTH="20%" 314TITLE="C3"><COL 315WIDTH="40%" 316TITLE="C4"><TBODY 317VALIGN="TOP" 318><TR 319><TD 320>__u32</TD 321><TD 322><CODE 323CLASS="STRUCTFIELD" 324>id</CODE 325></TD 326><TD 327> </TD 328><TD 329>Identifies the control, set by the 330application.</TD 331></TR 332><TR 333><TD 334>__u32</TD 335><TD 336><CODE 337CLASS="STRUCTFIELD" 338>reserved2</CODE 339>[2]</TD 340><TD 341> </TD 342><TD 343>Reserved for future extensions. Drivers and 344applications must set the array to zero.</TD 345></TR 346><TR 347><TD 348>union</TD 349><TD 350>(anonymous)</TD 351><TD 352> </TD 353><TD 354> </TD 355></TR 356><TR 357><TD 358> </TD 359><TD 360>__s32</TD 361><TD 362><CODE 363CLASS="STRUCTFIELD" 364>value</CODE 365></TD 366><TD 367>New value or current value.</TD 368></TR 369><TR 370><TD 371> </TD 372><TD 373>__s64</TD 374><TD 375><CODE 376CLASS="STRUCTFIELD" 377>value64</CODE 378></TD 379><TD 380>New value or current value.</TD 381></TR 382><TR 383><TD 384> </TD 385><TD 386>void *</TD 387><TD 388><CODE 389CLASS="STRUCTFIELD" 390>reserved</CODE 391></TD 392><TD 393>Reserved for future pointer-type controls. Currently unused.</TD 394></TR 395></TBODY 396></TABLE 397></DIV 398><DIV 399CLASS="TABLE" 400><A 401NAME="V4L2-EXT-CONTROLS" 402></A 403><P 404><B 405>Table 2. struct <CODE 406CLASS="STRUCTNAME" 407>v4l2_ext_controls</CODE 408></B 409></P 410><TABLE 411BORDER="0" 412FRAME="void" 413WIDTH="100%" 414CLASS="CALSTABLE" 415><COL 416WIDTH="25%" 417TITLE="C1"><COL 418WIDTH="25%" 419TITLE="C2"><COL 420WIDTH="50%" 421TITLE="C3"><TBODY 422VALIGN="TOP" 423><TR 424><TD 425>__u32</TD 426><TD 427><CODE 428CLASS="STRUCTFIELD" 429>ctrl_class</CODE 430></TD 431><TD 432>The control class to which all controls belong, see 433<A 434HREF="r10386.htm#CTRL-CLASS" 435>Table 3</A 436>.</TD 437></TR 438><TR 439><TD 440>__u32</TD 441><TD 442><CODE 443CLASS="STRUCTFIELD" 444>count</CODE 445></TD 446><TD 447>The number of controls in the controls array. May 448also be zero.</TD 449></TR 450><TR 451><TD 452>__u32</TD 453><TD 454><CODE 455CLASS="STRUCTFIELD" 456>error_idx</CODE 457></TD 458><TD 459>Set by the driver in case of an error. It is the 460index of the control causing the error or equal to 'count' when the 461error is not associated with a particular control. Undefined when the 462ioctl returns 0 (success).</TD 463></TR 464><TR 465><TD 466>__u32</TD 467><TD 468><CODE 469CLASS="STRUCTFIELD" 470>reserved</CODE 471>[2]</TD 472><TD 473>Reserved for future extensions. Drivers and 474applications must set the array to zero.</TD 475></TR 476><TR 477><TD 478>struct <A 479HREF="r10386.htm#V4L2-EXT-CONTROL" 480>v4l2_ext_control</A 481> *</TD 482><TD 483><CODE 484CLASS="STRUCTFIELD" 485>controls</CODE 486></TD 487><TD 488>Pointer to an array of 489<CODE 490CLASS="STRUCTFIELD" 491>count</CODE 492> v4l2_ext_control structures. Ignored 493if <CODE 494CLASS="STRUCTFIELD" 495>count</CODE 496> equals zero.</TD 497></TR 498></TBODY 499></TABLE 500></DIV 501><DIV 502CLASS="TABLE" 503><A 504NAME="CTRL-CLASS" 505></A 506><P 507><B 508>Table 3. Control classes</B 509></P 510><TABLE 511BORDER="0" 512FRAME="void" 513WIDTH="100%" 514CLASS="CALSTABLE" 515><COL 516WIDTH="38%" 517TITLE="C1"><COL 518WIDTH="12%" 519TITLE="C2"><COL 520WIDTH="50%" 521TITLE="C3"><TBODY 522VALIGN="TOP" 523><TR 524><TD 525><CODE 526CLASS="CONSTANT" 527>V4L2_CTRL_CLASS_USER</CODE 528></TD 529><TD 530>0x980000</TD 531><TD 532>The class containing user controls. These controls 533are described in <A 534HREF="x542.htm" 535>Section 1.8</A 536>. All controls that can be set 537using the <A 538HREF="r10104.htm" 539><CODE 540CLASS="CONSTANT" 541>VIDIOC_S_CTRL</CODE 542></A 543> and <A 544HREF="r10104.htm" 545><CODE 546CLASS="CONSTANT" 547>VIDIOC_G_CTRL</CODE 548></A 549> ioctl belong to this 550class.</TD 551></TR 552><TR 553><TD 554><CODE 555CLASS="CONSTANT" 556>V4L2_CTRL_CLASS_MPEG</CODE 557></TD 558><TD 559>0x990000</TD 560><TD 561>The class containing MPEG compression controls. 562These controls are described in section <A 563HREF="x802.htm#MPEG-CONTROLS" 564>Section 1.9.5</A 565>.</TD 566></TR 567></TBODY 568></TABLE 569></DIV 570></DIV 571><DIV 572CLASS="REFSECT1" 573><A 574NAME="AEN10565" 575></A 576><H2 577>Return Value</H2 578><P 579>On success <SPAN 580CLASS="RETURNVALUE" 581>0</SPAN 582> is returned, on error <SPAN 583CLASS="RETURNVALUE" 584>-1</SPAN 585> and the <CODE 586CLASS="VARNAME" 587>errno</CODE 588> variable is set appropriately:</P 589><P 590></P 591><DIV 592CLASS="VARIABLELIST" 593><DL 594><DT 595><SPAN 596CLASS="ERRORCODE" 597>EINVAL</SPAN 598></DT 599><DD 600><P 601>The struct <A 602HREF="r10386.htm#V4L2-EXT-CONTROL" 603>v4l2_ext_control</A 604> <CODE 605CLASS="STRUCTFIELD" 606>id</CODE 607> 608is invalid or the struct <A 609HREF="r10386.htm#V4L2-EXT-CONTROLS" 610>v4l2_ext_controls</A 611> 612<CODE 613CLASS="STRUCTFIELD" 614>ctrl_class</CODE 615> is invalid. This error code is 616also returned by the <CODE 617CLASS="CONSTANT" 618>VIDIOC_S_EXT_CTRLS</CODE 619> and 620<CODE 621CLASS="CONSTANT" 622>VIDIOC_TRY_EXT_CTRLS</CODE 623> ioctls if two or more 624control values are in conflict.</P 625></DD 626><DT 627><SPAN 628CLASS="ERRORCODE" 629>ERANGE</SPAN 630></DT 631><DD 632><P 633>The struct <A 634HREF="r10386.htm#V4L2-EXT-CONTROL" 635>v4l2_ext_control</A 636> <CODE 637CLASS="STRUCTFIELD" 638>value</CODE 639> 640is out of bounds.</P 641></DD 642><DT 643><SPAN 644CLASS="ERRORCODE" 645>EBUSY</SPAN 646></DT 647><DD 648><P 649>The control is temporarily not changeable, possibly 650because another applications took over control of the device function 651this control belongs to.</P 652></DD 653></DL 654></DIV 655></DIV 656><DIV 657CLASS="NAVFOOTER" 658><HR 659ALIGN="LEFT" 660WIDTH="100%"><TABLE 661SUMMARY="Footer navigation table" 662WIDTH="100%" 663BORDER="0" 664CELLPADDING="0" 665CELLSPACING="0" 666><TR 667><TD 668WIDTH="33%" 669ALIGN="left" 670VALIGN="top" 671><A 672HREF="r10211.htm" 673ACCESSKEY="P" 674>Prev</A 675></TD 676><TD 677WIDTH="34%" 678ALIGN="center" 679VALIGN="top" 680><A 681HREF="book1.htm" 682ACCESSKEY="H" 683>Home</A 684></TD 685><TD 686WIDTH="33%" 687ALIGN="right" 688VALIGN="top" 689><A 690HREF="r10595.htm" 691ACCESSKEY="N" 692>Next</A 693></TD 694></TR 695><TR 696><TD 697WIDTH="33%" 698ALIGN="left" 699VALIGN="top" 700>ioctl VIDIOC_G_ENC_INDEX</TD 701><TD 702WIDTH="34%" 703ALIGN="center" 704VALIGN="top" 705><A 706HREF="r7624.htm" 707ACCESSKEY="U" 708>Up</A 709></TD 710><TD 711WIDTH="33%" 712ALIGN="right" 713VALIGN="top" 714>ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF</TD 715></TR 716></TABLE 717></DIV 718></BODY 719></HTML 720> 721