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