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/userspace-api/media/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***************************
13Digital TV frontend open()
14***************************
15
16Name
17====
18
19fe-open - Open a frontend device
20
21
22Synopsis
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
33Arguments
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
55Description
56===========
57
58This system call opens a named frontend device
59(``/dev/dvb/adapter?/frontend?``) for subsequent use. Usually the first
60thing to do after a successful open is to find out the frontend type
61with :ref:`FE_GET_INFO`.
62
63The device can be opened in read-only mode, which only allows monitoring
64of device status and statistics, or read/write mode, which allows any
65kind of use (e.g. performing tuning operations.)
66
67In a system with multiple front-ends, it is usually the case that
68multiple devices cannot be open in read/write mode simultaneously. As
69long as a front-end device is opened in read/write mode, other open()
70calls in read/write mode will either fail or block, depending on whether
71non-blocking or blocking mode was specified. A front-end device opened
72in blocking mode can later be put into non-blocking mode (and vice
73versa) using the F_SETFL command of the fcntl system call. This is a
74standard system call, documented in the Linux manual page for fcntl.
75When an open() call has succeeded, the device will be ready for use in
76the specified mode. This implies that the corresponding hardware is
77powered up, and that other front-ends may have been powered down to make
78that possible.
79
80
81Return Value
82============
83
84On success :ref:`open() <frontend_f_open>` returns the new file descriptor.
85On error, -1 is returned, and the ``errno`` variable is set appropriately.
86
87Possible error codes are:
88
89
90On success 0 is returned, and :c:type:`ca_slot_info` is filled.
91
92On error -1 is returned, and the ``errno`` variable is set
93appropriately.
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
116The generic error codes are described at the
117:ref:`Generic Error Codes <gen-errors>` chapter.
118