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