Documentation/media/uapi/dvb/frontend_f_open.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _frontend_f_open:
  11
  12 ***************************
  13 Digital TV frontend open()
  14 ***************************
  15
  16 Name
  17 ====
  18
  19 fe-open - Open a frontend device
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. code-block:: c
  26
  27     #include <fcntl.h>
  28
  29
  30 .. c:function:: int open( const char *device_name, int flags )
  31     :name: dvb-fe-open
  32
  33 Arguments
  34 =========
  35
  36 ``device_name``
  37     Device to be opened.
  38
  39 ``flags``
  40     Open flags. Access can either be ``O_RDWR`` or ``O_RDONLY``.
  41
  42     Multiple opens are allowed with ``O_RDONLY``. In this mode, only
  43     query and read ioctls are allowed.
  44
  45     Only one open is allowed in ``O_RDWR``. In this mode, all ioctls are
  46     allowed.
  47
  48     When the ``O_NONBLOCK`` flag is given, the system calls may return
  49     ``EAGAIN`` error code when no data is available or when the device
  50     driver is temporarily busy.
  51
  52     Other flags have no effect.
  53
  54
  55 Description
  56 ===========
  57
  58 This system call opens a named frontend device
  59 (``/dev/dvb/adapter?/frontend?``) for subsequent use. Usually the first
  60 thing to do after a successful open is to find out the frontend type
  61 with :ref:`FE_GET_INFO`.
  62
  63 The device can be opened in read-only mode, which only allows monitoring
  64 of device status and statistics, or read/write mode, which allows any
  65 kind of use (e.g. performing tuning operations.)
  66
  67 In a system with multiple front-ends, it is usually the case that
  68 multiple devices cannot be open in read/write mode simultaneously. As
  69 long as a front-end device is opened in read/write mode, other open()
  70 calls in read/write mode will either fail or block, depending on whether
  71 non-blocking or blocking mode was specified. A front-end device opened
  72 in blocking mode can later be put into non-blocking mode (and vice
  73 versa) using the F_SETFL command of the fcntl system call. This is a
  74 standard system call, documented in the Linux manual page for fcntl.
  75 When an open() call has succeeded, the device will be ready for use in
  76 the specified mode. This implies that the corresponding hardware is
  77 powered up, and that other front-ends may have been powered down to make
  78 that possible.
  79
  80
  81 Return Value
  82 ============
  83
  84 On success :ref:`open() <frontend_f_open>` returns the new file descriptor.
  85 On error, -1 is returned, and the ``errno`` variable is set appropriately.
  86
  87 Possible error codes are:
  88
  89
  90 On success 0 is returned, and :c:type:`ca_slot_info` is filled.
  91
  92 On error -1 is returned, and the ``errno`` variable is set
  93 appropriately.
  94
  95 .. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
  96
  97 .. flat-table::
  98     :header-rows:  0
  99     :stub-columns: 0
 100     :widths: 1 16
 101
 102     -  - ``EPERM``
 103        -  The caller has no permission to access the device.
 104
 105     -  - ``EBUSY``
 106        -  The the device driver is already in use.
 107
 108     -  - ``EMFILE``
 109        -  The process already has the maximum number of files open.
 110
 111     -  - ``ENFILE``
 112        -  The limit on the total number of files open on the system has been
 113           reached.
 114
 115
 116 The generic error codes are described at the
 117 :ref:`Generic Error Codes <gen-errors>` chapter.