| 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. |