0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: DTV.fe
0003
0004 .. _frontend_f_open:
0005
0006 ***************************
0007 Digital TV frontend open()
0008 ***************************
0009
0010 Name
0011 ====
0012
0013 fe-open - Open a frontend device
0014
0015 Synopsis
0016 ========
0017
0018 .. code-block:: c
0019
0020 #include <fcntl.h>
0021
0022 .. c:function:: int open( const char *device_name, int flags )
0023
0024 Arguments
0025 =========
0026
0027 ``device_name``
0028 Device to be opened.
0029
0030 ``flags``
0031 Open flags. Access can either be ``O_RDWR`` or ``O_RDONLY``.
0032
0033 Multiple opens are allowed with ``O_RDONLY``. In this mode, only
0034 query and read ioctls are allowed.
0035
0036 Only one open is allowed in ``O_RDWR``. In this mode, all ioctls are
0037 allowed.
0038
0039 When the ``O_NONBLOCK`` flag is given, the system calls may return
0040 ``EAGAIN`` error code when no data is available or when the device
0041 driver is temporarily busy.
0042
0043 Other flags have no effect.
0044
0045 Description
0046 ===========
0047
0048 This system call opens a named frontend device
0049 (``/dev/dvb/adapter?/frontend?``) for subsequent use. Usually the first
0050 thing to do after a successful open is to find out the frontend type
0051 with :ref:`FE_GET_INFO`.
0052
0053 The device can be opened in read-only mode, which only allows monitoring
0054 of device status and statistics, or read/write mode, which allows any
0055 kind of use (e.g. performing tuning operations.)
0056
0057 In a system with multiple front-ends, it is usually the case that
0058 multiple devices cannot be open in read/write mode simultaneously. As
0059 long as a front-end device is opened in read/write mode, other open()
0060 calls in read/write mode will either fail or block, depending on whether
0061 non-blocking or blocking mode was specified. A front-end device opened
0062 in blocking mode can later be put into non-blocking mode (and vice
0063 versa) using the F_SETFL command of the fcntl system call. This is a
0064 standard system call, documented in the Linux manual page for fcntl.
0065 When an open() call has succeeded, the device will be ready for use in
0066 the specified mode. This implies that the corresponding hardware is
0067 powered up, and that other front-ends may have been powered down to make
0068 that possible.
0069
0070 Return Value
0071 ============
0072
0073 On success :c:func:`open()` returns the new file descriptor.
0074 On error, -1 is returned, and the ``errno`` variable is set appropriately.
0075
0076 Possible error codes are:
0077
0078 On success 0 is returned, and :c:type:`ca_slot_info` is filled.
0079
0080 On error -1 is returned, and the ``errno`` variable is set
0081 appropriately.
0082
0083 .. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
0084
0085 .. flat-table::
0086 :header-rows: 0
0087 :stub-columns: 0
0088 :widths: 1 16
0089
0090 - - ``EPERM``
0091 - The caller has no permission to access the device.
0092
0093 - - ``EBUSY``
0094 - The the device driver is already in use.
0095
0096 - - ``EMFILE``
0097 - The process already has the maximum number of files open.
0098
0099 - - ``ENFILE``
0100 - The limit on the total number of files open on the system has been
0101 reached.
0102
0103 The generic error codes are described at the
0104 :ref:`Generic Error Codes <gen-errors>` chapter.
