Documentation/DocBook/dvb/demux.xml

   1 <title>DVB Demux Device</title>
   2
   3 <para>The DVB demux device controls the filters of the DVB hardware/software. It can be
   4 accessed through <emphasis role="tt">/dev/adapter0/demux0</emphasis>. Data types and and ioctl definitions can be
   5 accessed by including <emphasis role="tt">linux/dvb/dmx.h</emphasis> in your application.
   6 </para>
   7 <section id="dmx_types">
   8 <title>Demux Data Types</title>
   9
  10 <section id="dmx_output_t">
  11 <title>dmx_output_t</title>
  12  <programlisting>
  13  typedef enum
  14  {
  15          DMX_OUT_DECODER,
  16          DMX_OUT_TAP,
  17          DMX_OUT_TS_TAP
  18  } dmx_output_t;
  19 </programlisting>
  20 <para><emphasis role="tt">DMX_OUT_TAP</emphasis> delivers the stream output to the demux device on which the ioctl is
  21 called.
  22 </para>
  23 <para><emphasis role="tt">DMX_OUT_TS_TAP</emphasis> routes output to the logical DVR device <emphasis role="tt">/dev/dvb/adapter0/dvr0</emphasis>,
  24 which delivers a TS multiplexed from all filters for which <emphasis role="tt">DMX_OUT_TS_TAP</emphasis> was
  25 specified.
  26 </para>
  27 </section>
  28
  29 <section id="dmx_input_t">
  30 <title>dmx_input_t</title>
  31  <programlisting>
  32  typedef enum
  33  {
  34          DMX_IN_FRONTEND,
  35          DMX_IN_DVR
  36  } dmx_input_t;
  37 </programlisting>
  38 </section>
  39
  40 <section id="dmx_pes_type_t">
  41 <title>dmx_pes_type_t</title>
  42  <programlisting>
  43  typedef enum
  44  {
  45          DMX_PES_AUDIO,
  46          DMX_PES_VIDEO,
  47          DMX_PES_TELETEXT,
  48          DMX_PES_SUBTITLE,
  49          DMX_PES_PCR,
  50          DMX_PES_OTHER
  51  } dmx_pes_type_t;
  52 </programlisting>
  53 </section>
  54
  55 <section id="dmx_event_t">
  56 <title>dmx_event_t</title>
  57  <programlisting>
  58  typedef enum
  59  {
  60          DMX_SCRAMBLING_EV,
  61          DMX_FRONTEND_EV
  62  } dmx_event_t;
  63 </programlisting>
  64 </section>
  65
  66 <section id="dmx_scrambling_status_t">
  67 <title>dmx_scrambling_status_t</title>
  68  <programlisting>
  69  typedef enum
  70  {
  71          DMX_SCRAMBLING_OFF,
  72          DMX_SCRAMBLING_ON
  73  } dmx_scrambling_status_t;
  74 </programlisting>
  75 </section>
  76
  77 <section id="dmx_filter">
  78 <title>struct dmx_filter</title>
  79  <programlisting>
  80  typedef struct dmx_filter
  81  {
  82          uint8_t         filter[DMX_FILTER_SIZE];
  83          uint8_t         mask[DMX_FILTER_SIZE];
  84  } dmx_filter_t;
  85 </programlisting>
  86 </section>
  87
  88 <section id="dmx_sct_filter_params">
  89 <title>struct dmx_sct_filter_params</title>
  90  <programlisting>
  91  struct dmx_sct_filter_params
  92  {
  93          uint16_t            pid;
  94          dmx_filter_t        filter;
  95          uint32_t            timeout;
  96          uint32_t            flags;
  97  #define DMX_CHECK_CRC       1
  98  #define DMX_ONESHOT         2
  99  #define DMX_IMMEDIATE_START 4
 100  };
 101 </programlisting>
 102 </section>
 103
 104 <section id="dmx_pes_filter_params">
 105 <title>struct dmx_pes_filter_params</title>
 106  <programlisting>
 107  struct dmx_pes_filter_params
 108  {
 109          uint16_t            pid;
 110          dmx_input_t         input;
 111          dmx_output_t        output;
 112          dmx_pes_type_t      pes_type;
 113          uint32_t            flags;
 114  };
 115 </programlisting>
 116 </section>
 117
 118 <section id="dmx_event">
 119 <title>struct dmx_event</title>
 120  <programlisting>
 121  struct dmx_event
 122  {
 123          dmx_event_t          event;
 124          time_t               timeStamp;
 125          union
 126          {
 127                  dmx_scrambling_status_t scrambling;
 128          } u;
 129  };
 130 </programlisting>
 131 </section>
 132
 133 <section id="dmx_stc">
 134 <title>struct dmx_stc</title>
 135  <programlisting>
 136  struct dmx_stc {
 137          unsigned int num;       /&#x22C6; input : which STC? 0..N &#x22C6;/
 138          unsigned int base;      /&#x22C6; output: divisor for stc to get 90 kHz clock &#x22C6;/
 139          uint64_t stc;           /&#x22C6; output: stc in 'base'&#x22C6;90 kHz units &#x22C6;/
 140  };
 141 </programlisting>
 142  </section>
 143
 144 </section>
 145
 146 <section id="dmx_fcalls">
 147 <title>Demux Function Calls</title>
 148
 149 <section id="dmx_fopen">
 150 <title>open()</title>
 151 <para>DESCRIPTION
 152 </para>
 153 <informaltable><tgroup cols="1"><tbody><row><entry
 154  align="char">
 155 <para>This system call, used with a device name of /dev/dvb/adapter0/demux0,
 156  allocates a new filter and returns a handle which can be used for subsequent
 157  control of that filter. This call has to be made for each filter to be used, i.e. every
 158  returned file descriptor is a reference to a single filter. /dev/dvb/adapter0/dvr0
 159  is a logical device to be used for retrieving Transport Streams for digital
 160  video recording. When reading from this device a transport stream containing
 161  the packets from all PES filters set in the corresponding demux device
 162  (/dev/dvb/adapter0/demux0) having the output set to DMX_OUT_TS_TAP. A
 163  recorded Transport Stream is replayed by writing to this device. </para>
 164 <para>The significance of blocking or non-blocking mode is described in the
 165  documentation for functions where there is a difference. It does not affect the
 166  semantics of the open() call itself. A device opened in blocking mode can later
 167  be put into non-blocking mode (and vice versa) using the F_SETFL command
 168  of the fcntl system call.</para>
 169 </entry>
 170  </row></tbody></tgroup></informaltable>
 171 <para>SYNOPSIS
 172 </para>
 173 <informaltable><tgroup cols="1"><tbody><row><entry
 174  align="char">
 175 <para>int open(const char &#x22C6;deviceName, int flags);</para>
 176 </entry>
 177  </row></tbody></tgroup></informaltable>
 178 <para>PARAMETERS
 179 </para>
 180 <informaltable><tgroup cols="2"><tbody><row><entry
 181  align="char">
 182 <para>const char
 183  *deviceName</para>
 184 </entry><entry
 185  align="char">
 186 <para>Name of demux device.</para>
 187 </entry>
 188  </row><row><entry
 189  align="char">
 190 <para>int flags</para>
 191 </entry><entry
 192  align="char">
 193 <para>A bit-wise OR of the following flags:</para>
 194 </entry>
 195  </row><row><entry
 196  align="char">
 197 </entry><entry
 198  align="char">
 199 <para>O_RDWR read/write access</para>
 200 </entry>
 201  </row><row><entry
 202  align="char">
 203 </entry><entry
 204  align="char">
 205 <para>O_NONBLOCK open in non-blocking mode</para>
 206 </entry>
 207  </row><row><entry
 208  align="char">
 209 </entry><entry
 210  align="char">
 211 <para>(blocking mode is the default)</para>
 212 </entry>
 213  </row></tbody></tgroup></informaltable>
 214 <para>ERRORS
 215 </para>
 216 <informaltable><tgroup cols="2"><tbody><row><entry
 217  align="char">
 218 <para>ENODEV</para>
 219 </entry><entry
 220  align="char">
 221 <para>Device driver not loaded/available.</para>
 222 </entry>
 223  </row><row><entry
 224  align="char">
 225 <para>EINVAL</para>
 226 </entry><entry
 227  align="char">
 228 <para>Invalid argument.</para>
 229 </entry>
 230  </row><row><entry
 231  align="char">
 232 <para>EMFILE</para>
 233 </entry><entry
 234  align="char">
 235 <para>&#8220;Too many open files&#8221;, i.e. no more filters available.</para>
 236 </entry>
 237  </row><row><entry
 238  align="char">
 239 <para>ENOMEM</para>
 240 </entry><entry
 241  align="char">
 242 <para>The driver failed to allocate enough memory.</para>
 243 </entry>
 244  </row></tbody></tgroup></informaltable>
 245 </section>
 246
 247 <section id="dmx_fclose">
 248 <title>close()</title>
 249 <para>DESCRIPTION
 250 </para>
 251 <informaltable><tgroup cols="1"><tbody><row><entry
 252  align="char">
 253 <para>This system call deactivates and deallocates a filter that was previously
 254  allocated via the open() call.</para>
 255 </entry>
 256  </row></tbody></tgroup></informaltable>
 257 <para>SYNOPSIS
 258 </para>
 259 <informaltable><tgroup cols="1"><tbody><row><entry
 260  align="char">
 261 <para>int close(int fd);</para>
 262 </entry>
 263  </row></tbody></tgroup></informaltable>
 264 <para>PARAMETERS
 265 </para>
 266 <informaltable><tgroup cols="2"><tbody><row><entry
 267  align="char">
 268 <para>int fd</para>
 269 </entry><entry
 270  align="char">
 271 <para>File descriptor returned by a previous call to open().</para>
 272 </entry>
 273  </row></tbody></tgroup></informaltable>
 274 <para>ERRORS
 275 </para>
 276 <informaltable><tgroup cols="2"><tbody><row><entry
 277  align="char">
 278 <para>EBADF</para>
 279 </entry><entry
 280  align="char">
 281 <para>fd is not a valid open file descriptor.</para>
 282 </entry>
 283  </row></tbody></tgroup></informaltable>
 284 </section>
 285
 286 <section id="dmx_fread">
 287 <title>read()</title>
 288 <para>DESCRIPTION
 289 </para>
 290 <informaltable><tgroup cols="1"><tbody><row><entry
 291  align="char">
 292 <para>This system call returns filtered data, which might be section or PES data. The
 293  filtered data is transferred from the driver&#8217;s internal circular buffer to buf. The
 294  maximum amount of data to be transferred is implied by count.</para>
 295 </entry>
 296  </row><row><entry
 297  align="char">
 298 <para>When returning section data the driver always tries to return a complete single
 299  section (even though buf would provide buffer space for more data). If the size
 300  of the buffer is smaller than the section as much as possible will be returned,
 301  and the remaining data will be provided in subsequent calls.</para>
 302 </entry>
 303  </row><row><entry
 304  align="char">
 305 <para>The size of the internal buffer is 2 * 4096 bytes (the size of two maximum
 306  sized sections) by default. The size of this buffer may be changed by using the
 307  DMX_SET_BUFFER_SIZE function. If the buffer is not large enough, or if
 308  the read operations are not performed fast enough, this may result in a buffer
 309  overflow error. In this case EOVERFLOW will be returned, and the circular
 310  buffer will be emptied. This call is blocking if there is no data to return, i.e. the
 311  process will be put to sleep waiting for data, unless the O_NONBLOCK flag
 312  is specified.</para>
 313 </entry>
 314  </row><row><entry
 315  align="char">
 316 <para>Note that in order to be able to read, the filtering process has to be started
 317  by defining either a section or a PES filter by means of the ioctl functions,
 318  and then starting the filtering process via the DMX_START ioctl function
 319  or by setting the DMX_IMMEDIATE_START flag. If the reading is done
 320  from a logical DVR demux device, the data will constitute a Transport Stream
 321  including the packets from all PES filters in the corresponding demux device
 322  /dev/dvb/adapter0/demux0 having the output set to DMX_OUT_TS_TAP.</para>
 323 </entry>
 324  </row></tbody></tgroup></informaltable>
 325 <para>SYNOPSIS
 326 </para>
 327 <informaltable><tgroup cols="1"><tbody><row><entry
 328  align="char">
 329 <para>size_t read(int fd, void &#x22C6;buf, size_t count);</para>
 330 </entry>
 331  </row></tbody></tgroup></informaltable>
 332 <para>PARAMETERS
 333 </para>
 334 <informaltable><tgroup cols="2"><tbody><row><entry
 335  align="char">
 336 <para>int fd</para>
 337 </entry><entry
 338  align="char">
 339 <para>File descriptor returned by a previous call to open().</para>
 340 </entry>
 341  </row><row><entry
 342  align="char">
 343 <para>void *buf</para>
 344 </entry><entry
 345  align="char">
 346 <para>Pointer to the buffer to be used for returned filtered data.</para>
 347 </entry>
 348  </row><row><entry
 349  align="char">
 350 <para>size_t count</para>
 351 </entry><entry
 352  align="char">
 353 <para>Size of buf.</para>
 354 </entry>
 355  </row></tbody></tgroup></informaltable>
 356 <para>ERRORS
 357 </para>
 358 <informaltable><tgroup cols="2"><tbody><row><entry
 359  align="char">
 360 <para>EWOULDBLOCK</para>
 361 </entry><entry
 362  align="char">
 363 <para>No data to return and O_NONBLOCK was specified.</para>
 364 </entry>
 365  </row><row><entry
 366  align="char">
 367 <para>EBADF</para>
 368 </entry><entry
 369  align="char">
 370 <para>fd is not a valid open file descriptor.</para>
 371 </entry>
 372  </row><row><entry
 373  align="char">
 374 <para>ECRC</para>
 375 </entry><entry
 376  align="char">
 377 <para>Last section had a CRC error - no data returned. The
 378  buffer is flushed.</para>
 379 </entry>
 380  </row><row><entry
 381  align="char">
 382 <para>EOVERFLOW</para>
 383 </entry><entry
 384  align="char">
 385 </entry>
 386  </row><row><entry
 387  align="char">
 388 </entry><entry
 389  align="char">
 390 <para>The filtered data was not read from the buffer in due
 391  time, resulting in non-read data being lost. The buffer is
 392  flushed.</para>
 393 </entry>
 394  </row><row><entry
 395  align="char">
 396 <para>ETIMEDOUT</para>
 397 </entry><entry
 398  align="char">
 399 <para>The section was not loaded within the stated timeout
 400  period. See ioctl DMX_SET_FILTER for how to set a
 401  timeout.</para>
 402 </entry>
 403  </row><row><entry
 404  align="char">
 405 <para>EFAULT</para>
 406 </entry><entry
 407  align="char">
 408 <para>The driver failed to write to the callers buffer due to an
 409  invalid *buf pointer.</para>
 410 </entry>
 411  </row></tbody></tgroup></informaltable>
 412 </section>
 413
 414 <section id="dmx_fwrite">
 415 <title>write()</title>
 416 <para>DESCRIPTION
 417 </para>
 418 <informaltable><tgroup cols="1"><tbody><row><entry
 419  align="char">
 420 <para>This system call is only provided by the logical device /dev/dvb/adapter0/dvr0,
 421  associated with the physical demux device that provides the actual DVR
 422  functionality. It is used for replay of a digitally recorded Transport Stream.
 423  Matching filters have to be defined in the corresponding physical demux
 424  device, /dev/dvb/adapter0/demux0. The amount of data to be transferred is
 425  implied by count.</para>
 426 </entry>
 427  </row></tbody></tgroup></informaltable>
 428 <para>SYNOPSIS
 429 </para>
 430 <informaltable><tgroup cols="1"><tbody><row><entry
 431  align="char">
 432 <para>ssize_t write(int fd, const void &#x22C6;buf, size_t
 433  count);</para>
 434 </entry>
 435  </row></tbody></tgroup></informaltable>
 436 <para>PARAMETERS
 437 </para>
 438 <informaltable><tgroup cols="2"><tbody><row><entry
 439  align="char">
 440 <para>int fd</para>
 441 </entry><entry
 442  align="char">
 443 <para>File descriptor returned by a previous call to open().</para>
 444 </entry>
 445  </row><row><entry
 446  align="char">
 447 <para>void *buf</para>
 448 </entry><entry
 449  align="char">
 450 <para>Pointer to the buffer containing the Transport Stream.</para>
 451 </entry>
 452  </row><row><entry
 453  align="char">
 454 <para>size_t count</para>
 455 </entry><entry
 456  align="char">
 457 <para>Size of buf.</para>
 458 </entry>
 459  </row></tbody></tgroup></informaltable>
 460 <para>ERRORS
 461 </para>
 462 <informaltable><tgroup cols="2"><tbody><row><entry
 463  align="char">
 464 <para>EWOULDBLOCK</para>
 465 </entry><entry
 466  align="char">
 467 <para>No data was written. This
 468  might happen if O_NONBLOCK was specified and there
 469  is no more buffer space available (if O_NONBLOCK is
 470  not specified the function will block until buffer space is
 471  available).</para>
 472 </entry>
 473  </row><row><entry
 474  align="char">
 475 <para>EBUSY</para>
 476 </entry><entry
 477  align="char">
 478 <para>This error code indicates that there are conflicting
 479  requests. The corresponding demux device is setup to
 480  receive data from the front- end. Make sure that these
 481  filters are stopped and that the filters with input set to
 482  DMX_IN_DVR are started.</para>
 483 </entry>
 484  </row><row><entry
 485  align="char">
 486 <para>EBADF</para>
 487 </entry><entry
 488  align="char">
 489 <para>fd is not a valid open file descriptor.</para>
 490 </entry>
 491  </row></tbody></tgroup></informaltable>
 492 </section>
 493
 494 <section id="dmx_start">
 495 <title>DMX_START</title>
 496 <para>DESCRIPTION
 497 </para>
 498 <informaltable><tgroup cols="1"><tbody><row><entry
 499  align="char">
 500 <para>This ioctl call is used to start the actual filtering operation defined via the ioctl
 501  calls DMX_SET_FILTER or DMX_SET_PES_FILTER.</para>
 502 </entry>
 503  </row></tbody></tgroup></informaltable>
 504 <para>SYNOPSIS
 505 </para>
 506 <informaltable><tgroup cols="1"><tbody><row><entry
 507  align="char">
 508 <para>int ioctl( int fd, int request = DMX_START);</para>
 509 </entry>
 510  </row></tbody></tgroup></informaltable>
 511 <para>PARAMETERS
 512 </para>
 513 <informaltable><tgroup cols="2"><tbody><row><entry
 514  align="char">
 515 <para>int fd</para>
 516 </entry><entry
 517  align="char">
 518 <para>File descriptor returned by a previous call to open().</para>
 519 </entry>
 520  </row><row><entry
 521  align="char">
 522 <para>int request</para>
 523 </entry><entry
 524  align="char">
 525 <para>Equals DMX_START for this command.</para>
 526 </entry>
 527  </row></tbody></tgroup></informaltable>
 528 <para>ERRORS
 529 </para>
 530 <informaltable><tgroup cols="2"><tbody><row><entry
 531  align="char">
 532 <para>EBADF</para>
 533 </entry><entry
 534  align="char">
 535 <para>fd is not a valid file descriptor.</para>
 536 </entry>
 537  </row><row><entry
 538  align="char">
 539 <para>EINVAL</para>
 540 </entry><entry
 541  align="char">
 542 <para>Invalid argument, i.e. no filtering parameters provided via
 543  the DMX_SET_FILTER or DMX_SET_PES_FILTER
 544  functions.</para>
 545 </entry>
 546  </row><row><entry
 547  align="char">
 548 <para>EBUSY</para>
 549 </entry><entry
 550  align="char">
 551 <para>This error code indicates that there are conflicting
 552  requests. There are active filters filtering data from
 553  another input source. Make sure that these filters are
 554  stopped before starting this filter.</para>
 555 </entry>
 556  </row></tbody></tgroup></informaltable>
 557 </section>
 558
 559 <section id="dmx_stop">
 560 <title>DMX_STOP</title>
 561 <para>DESCRIPTION
 562 </para>
 563 <informaltable><tgroup cols="1"><tbody><row><entry
 564  align="char">
 565 <para>This ioctl call is used to stop the actual filtering operation defined via the
 566  ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER and started via
 567  the DMX_START command.</para>
 568 </entry>
 569  </row></tbody></tgroup></informaltable>
 570 <para>SYNOPSIS
 571 </para>
 572 <informaltable><tgroup cols="1"><tbody><row><entry
 573  align="char">
 574 <para>int ioctl( int fd, int request = DMX_STOP);</para>
 575 </entry>
 576  </row></tbody></tgroup></informaltable>
 577 <para>PARAMETERS
 578 </para>
 579 <informaltable><tgroup cols="2"><tbody><row><entry
 580  align="char">
 581 <para>int fd</para>
 582 </entry><entry
 583  align="char">
 584 <para>File descriptor returned by a previous call to open().</para>
 585 </entry>
 586  </row><row><entry
 587  align="char">
 588 <para>int request</para>
 589 </entry><entry
 590  align="char">
 591 <para>Equals DMX_STOP for this command.</para>
 592 </entry>
 593  </row></tbody></tgroup></informaltable>
 594 <para>ERRORS
 595 </para>
 596 <informaltable><tgroup cols="2"><tbody><row><entry
 597  align="char">
 598 <para>EBADF</para>
 599 </entry><entry
 600  align="char">
 601 <para>fd is not a valid file descriptor.</para>
 602 </entry>
 603  </row></tbody></tgroup></informaltable>
 604 </section>
 605
 606 <section id="dmx_set_filter">
 607 <title>DMX_SET_FILTER</title>
 608 <para>DESCRIPTION
 609 </para>
 610 <informaltable><tgroup cols="1"><tbody><row><entry
 611  align="char">
 612 <para>This ioctl call sets up a filter according to the filter and mask parameters
 613  provided. A timeout may be defined stating number of seconds to wait for a
 614  section to be loaded. A value of 0 means that no timeout should be applied.
 615  Finally there is a flag field where it is possible to state whether a section should
 616  be CRC-checked, whether the filter should be a &#8221;one-shot&#8221; filter, i.e. if the
 617  filtering operation should be stopped after the first section is received, and
 618  whether the filtering operation should be started immediately (without waiting
 619  for a DMX_START ioctl call). If a filter was previously set-up, this filter will
 620  be canceled, and the receive buffer will be flushed.</para>
 621 </entry>
 622  </row></tbody></tgroup></informaltable>
 623 <para>SYNOPSIS
 624 </para>
 625 <informaltable><tgroup cols="1"><tbody><row><entry
 626  align="char">
 627 <para>int ioctl( int fd, int request = DMX_SET_FILTER,
 628  struct dmx_sct_filter_params &#x22C6;params);</para>
 629 </entry>
 630  </row></tbody></tgroup></informaltable>
 631 <para>PARAMETERS
 632 </para>
 633 <informaltable><tgroup cols="2"><tbody><row><entry
 634  align="char">
 635 <para>int fd</para>
 636 </entry><entry
 637  align="char">
 638 <para>File descriptor returned by a previous call to open().</para>
 639 </entry>
 640  </row><row><entry
 641  align="char">
 642 <para>int request</para>
 643 </entry><entry
 644  align="char">
 645 <para>Equals DMX_SET_FILTER for this command.</para>
 646 </entry>
 647  </row><row><entry
 648  align="char">
 649 <para>struct
 650  dmx_sct_filter_params
 651  *params</para>
 652 </entry><entry
 653  align="char">
 654 <para>Pointer to structure containing filter parameters.</para>
 655 </entry>
 656  </row></tbody></tgroup></informaltable>
 657 <para>ERRORS
 658 </para>
 659 <informaltable><tgroup cols="2"><tbody><row><entry
 660  align="char">
 661 <para>EBADF</para>
 662 </entry><entry
 663  align="char">
 664 <para>fd is not a valid file descriptor.</para>
 665 </entry>
 666  </row><row><entry
 667  align="char">
 668 <para>EINVAL</para>
 669 </entry><entry
 670  align="char">
 671 <para>Invalid argument.</para>
 672 </entry>
 673  </row></tbody></tgroup></informaltable>
 674 </section>
 675
 676 <section id="dmx_set_pes_filter">
 677 <title>DMX_SET_PES_FILTER</title>
 678 <para>DESCRIPTION
 679 </para>
 680 <informaltable><tgroup cols="1"><tbody><row><entry
 681  align="char">
 682 <para>This ioctl call sets up a PES filter according to the parameters provided. By a
 683  PES filter is meant a filter that is based just on the packet identifier (PID), i.e.
 684  no PES header or payload filtering capability is supported.</para>
 685 </entry>
 686  </row><row><entry
 687  align="char">
 688 <para>The transport stream destination for the filtered output may be set. Also the
 689  PES type may be stated in order to be able to e.g. direct a video stream directly
 690  to the video decoder. Finally there is a flag field where it is possible to state
 691  whether the filtering operation should be started immediately (without waiting
 692  for a DMX_START ioctl call). If a filter was previously set-up, this filter will
 693  be cancelled, and the receive buffer will be flushed.</para>
 694 </entry>
 695  </row></tbody></tgroup></informaltable>
 696 <para>SYNOPSIS
 697 </para>
 698 <informaltable><tgroup cols="1"><tbody><row><entry
 699  align="char">
 700 <para>int ioctl( int fd, int request = DMX_SET_PES_FILTER,
 701  struct dmx_pes_filter_params &#x22C6;params);</para>
 702 </entry>
 703  </row></tbody></tgroup></informaltable>
 704 <para>PARAMETERS
 705 </para>
 706 <informaltable><tgroup cols="2"><tbody><row><entry
 707  align="char">
 708 <para>int fd</para>
 709 </entry><entry
 710  align="char">
 711 <para>File descriptor returned by a previous call to open().</para>
 712 </entry>
 713  </row><row><entry
 714  align="char">
 715 <para>int request</para>
 716 </entry><entry
 717  align="char">
 718 <para>Equals DMX_SET_PES_FILTER for this command.</para>
 719 </entry>
 720  </row><row><entry
 721  align="char">
 722 <para>struct
 723  dmx_pes_filter_params
 724  *params</para>
 725 </entry><entry
 726  align="char">
 727 <para>Pointer to structure containing filter parameters.</para>
 728 </entry>
 729  </row></tbody></tgroup></informaltable>
 730 <para>ERRORS
 731 </para>
 732 <informaltable><tgroup cols="2"><tbody><row><entry
 733  align="char">
 734 <para>EBADF</para>
 735 </entry><entry
 736  align="char">
 737 <para>fd is not a valid file descriptor.</para>
 738 </entry>
 739  </row><row><entry
 740  align="char">
 741 <para>EINVAL</para>
 742 </entry><entry
 743  align="char">
 744 <para>Invalid argument.</para>
 745 </entry>
 746  </row><row><entry
 747  align="char">
 748 <para>EBUSY</para>
 749 </entry><entry
 750  align="char">
 751 <para>This error code indicates that there are conflicting
 752  requests. There are active filters filtering data from
 753  another input source. Make sure that these filters are
 754  stopped before starting this filter.</para>
 755 </entry>
 756  </row></tbody></tgroup></informaltable>
 757 </section>
 758
 759 <section id="dms_set_buffer_size">
 760 <title>DMX_SET_BUFFER_SIZE</title>
 761 <para>DESCRIPTION
 762 </para>
 763 <informaltable><tgroup cols="1"><tbody><row><entry
 764  align="char">
 765 <para>This ioctl call is used to set the size of the circular buffer used for filtered data.
 766  The default size is two maximum sized sections, i.e. if this function is not called
 767  a buffer size of 2 * 4096 bytes will be used.</para>
 768 </entry>
 769  </row></tbody></tgroup></informaltable>
 770 <para>SYNOPSIS
 771 </para>
 772 <informaltable><tgroup cols="1"><tbody><row><entry
 773  align="char">
 774 <para>int ioctl( int fd, int request =
 775  DMX_SET_BUFFER_SIZE, unsigned long size);</para>
 776 </entry>
 777  </row></tbody></tgroup></informaltable>
 778 <para>PARAMETERS
 779 </para>
 780 <informaltable><tgroup cols="2"><tbody><row><entry
 781  align="char">
 782 <para>int fd</para>
 783 </entry><entry
 784  align="char">
 785 <para>File descriptor returned by a previous call to open().</para>
 786 </entry>
 787  </row><row><entry
 788  align="char">
 789 <para>int request</para>
 790 </entry><entry
 791  align="char">
 792 <para>Equals DMX_SET_BUFFER_SIZE for this command.</para>
 793 </entry>
 794  </row><row><entry
 795  align="char">
 796 <para>unsigned long size</para>
 797 </entry><entry
 798  align="char">
 799 <para>Size of circular buffer.</para>
 800 </entry>
 801  </row></tbody></tgroup></informaltable>
 802 <para>ERRORS
 803 </para>
 804 <informaltable><tgroup cols="2"><tbody><row><entry
 805  align="char">
 806 <para>EBADF</para>
 807 </entry><entry
 808  align="char">
 809 <para>fd is not a valid file descriptor.</para>
 810 </entry>
 811  </row><row><entry
 812  align="char">
 813 <para>ENOMEM</para>
 814 </entry><entry
 815  align="char">
 816 <para>The driver was not able to allocate a buffer of the
 817  requested size.</para>
 818 </entry>
 819  </row></tbody></tgroup></informaltable>
 820 </section>
 821
 822 <section id="dmx_get_event">
 823 <title>DMX_GET_EVENT</title>
 824 <para>DESCRIPTION
 825 </para>
 826 <informaltable><tgroup cols="1"><tbody><row><entry
 827  align="char">
 828 <para>This ioctl call returns an event if available. If an event is not available,
 829  the behavior depends on whether the device is in blocking or non-blocking
 830  mode. In the latter case, the call fails immediately with errno set to
 831  EWOULDBLOCK. In the former case, the call blocks until an event becomes
 832  available.</para>
 833 </entry>
 834  </row><row><entry
 835  align="char">
 836 <para>The standard Linux poll() and/or select() system calls can be used with the
 837  device file descriptor to watch for new events. For select(), the file descriptor
 838  should be included in the exceptfds argument, and for poll(), POLLPRI should
 839  be specified as the wake-up condition. Only the latest event for each filter is
 840  saved.</para>
 841 </entry>
 842  </row></tbody></tgroup></informaltable>
 843 <para>SYNOPSIS
 844 </para>
 845 <informaltable><tgroup cols="1"><tbody><row><entry
 846  align="char">
 847 <para>int ioctl( int fd, int request = DMX_GET_EVENT,
 848  struct dmx_event &#x22C6;ev);</para>
 849 </entry>
 850  </row></tbody></tgroup></informaltable>
 851 <para>PARAMETERS
 852 </para>
 853 <informaltable><tgroup cols="2"><tbody><row><entry
 854  align="char">
 855 <para>int fd</para>
 856 </entry><entry
 857  align="char">
 858 <para>File descriptor returned by a previous call to open().</para>
 859 </entry>
 860  </row><row><entry
 861  align="char">
 862 <para>int request</para>
 863 </entry><entry
 864  align="char">
 865 <para>Equals DMX_GET_EVENT for this command.</para>
 866 </entry>
 867  </row><row><entry
 868  align="char">
 869 <para>struct dmx_event *ev</para>
 870 </entry><entry
 871  align="char">
 872 <para>Pointer to the location where the event is to be stored.</para>
 873 </entry>
 874  </row></tbody></tgroup></informaltable>
 875 <para>ERRORS
 876 </para>
 877 <informaltable><tgroup cols="2"><tbody><row><entry
 878  align="char">
 879 <para>EBADF</para>
 880 </entry><entry
 881  align="char">
 882 <para>fd is not a valid file descriptor.</para>
 883 </entry>
 884  </row><row><entry
 885  align="char">
 886 <para>EFAULT</para>
 887 </entry><entry
 888  align="char">
 889 <para>ev points to an invalid address.</para>
 890 </entry>
 891  </row><row><entry
 892  align="char">
 893 <para>EWOULDBLOCK</para>
 894 </entry><entry
 895  align="char">
 896 <para>There is no event pending, and the device is in
 897  non-blocking mode.</para>
 898 </entry>
 899  </row></tbody></tgroup></informaltable>
 900 </section>
 901
 902 <section id="dmx_get_stc">
 903 <title>DMX_GET_STC</title>
 904 <para>DESCRIPTION
 905 </para>
 906 <informaltable><tgroup cols="1"><tbody><row><entry
 907  align="char">
 908 <para>This ioctl call returns the current value of the system time counter (which is driven
 909  by a PES filter of type DMX_PES_PCR). Some hardware supports more than one
 910  STC, so you must specify which one by setting the num field of stc before the ioctl
 911  (range 0...n). The result is returned in form of a ratio with a 64 bit numerator
 912  and a 32 bit denominator, so the real 90kHz STC value is stc-&#x003E;stc /
 913  stc-&#x003E;base
 914  .</para>
 915 </entry>
 916  </row></tbody></tgroup></informaltable>
 917 <para>SYNOPSIS
 918 </para>
 919 <informaltable><tgroup cols="1"><tbody><row><entry
 920  align="char">
 921 <para>int ioctl( int fd, int request = DMX_GET_STC, struct
 922  dmx_stc &#x22C6;stc);</para>
 923 </entry>
 924  </row></tbody></tgroup></informaltable>
 925 <para>PARAMETERS
 926 </para>
 927 <informaltable><tgroup cols="2"><tbody><row><entry
 928  align="char">
 929 <para>int fd</para>
 930 </entry><entry
 931  align="char">
 932 <para>File descriptor returned by a previous call to open().</para>
 933 </entry>
 934  </row><row><entry
 935  align="char">
 936 <para>int request</para>
 937 </entry><entry
 938  align="char">
 939 <para>Equals DMX_GET_STC for this command.</para>
 940 </entry>
 941  </row><row><entry
 942  align="char">
 943 <para>struct dmx_stc *stc</para>
 944 </entry><entry
 945  align="char">
 946 <para>Pointer to the location where the stc is to be stored.</para>
 947 </entry>
 948  </row></tbody></tgroup></informaltable>
 949 <para>ERRORS
 950 </para>
 951 <informaltable><tgroup cols="2"><tbody><row><entry
 952  align="char">
 953 <para>EBADF</para>
 954 </entry><entry
 955  align="char">
 956 <para>fd is not a valid file descriptor.</para>
 957 </entry>
 958  </row><row><entry
 959  align="char">
 960 <para>EFAULT</para>
 961 </entry><entry
 962  align="char">
 963 <para>stc points to an invalid address.</para>
 964 </entry>
 965  </row><row><entry
 966  align="char">
 967 <para>EINVAL</para>
 968 </entry><entry
 969  align="char">
 970 <para>Invalid stc number.</para>
 971 </entry>
 972  </row></tbody></tgroup></informaltable>
 973  </section></section>