1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 254f38fcaSMauro Carvalho Chehab 354f38fcaSMauro Carvalho Chehab.. _frontend_f_open: 454f38fcaSMauro Carvalho Chehab 554f38fcaSMauro Carvalho Chehab*************************** 654f38fcaSMauro Carvalho ChehabDigital TV frontend open() 754f38fcaSMauro Carvalho Chehab*************************** 854f38fcaSMauro Carvalho Chehab 954f38fcaSMauro Carvalho ChehabName 1054f38fcaSMauro Carvalho Chehab==== 1154f38fcaSMauro Carvalho Chehab 1254f38fcaSMauro Carvalho Chehabfe-open - Open a frontend device 1354f38fcaSMauro Carvalho Chehab 1454f38fcaSMauro Carvalho Chehab 1554f38fcaSMauro Carvalho ChehabSynopsis 1654f38fcaSMauro Carvalho Chehab======== 1754f38fcaSMauro Carvalho Chehab 1854f38fcaSMauro Carvalho Chehab.. code-block:: c 1954f38fcaSMauro Carvalho Chehab 2054f38fcaSMauro Carvalho Chehab #include <fcntl.h> 2154f38fcaSMauro Carvalho Chehab 2254f38fcaSMauro Carvalho Chehab 2354f38fcaSMauro Carvalho Chehab.. c:function:: int open( const char *device_name, int flags ) 2454f38fcaSMauro Carvalho Chehab :name: dvb-fe-open 2554f38fcaSMauro Carvalho Chehab 2654f38fcaSMauro Carvalho ChehabArguments 2754f38fcaSMauro Carvalho Chehab========= 2854f38fcaSMauro Carvalho Chehab 2954f38fcaSMauro Carvalho Chehab``device_name`` 3054f38fcaSMauro Carvalho Chehab Device to be opened. 3154f38fcaSMauro Carvalho Chehab 3254f38fcaSMauro Carvalho Chehab``flags`` 3354f38fcaSMauro Carvalho Chehab Open flags. Access can either be ``O_RDWR`` or ``O_RDONLY``. 3454f38fcaSMauro Carvalho Chehab 3554f38fcaSMauro Carvalho Chehab Multiple opens are allowed with ``O_RDONLY``. In this mode, only 3654f38fcaSMauro Carvalho Chehab query and read ioctls are allowed. 3754f38fcaSMauro Carvalho Chehab 3854f38fcaSMauro Carvalho Chehab Only one open is allowed in ``O_RDWR``. In this mode, all ioctls are 3954f38fcaSMauro Carvalho Chehab allowed. 4054f38fcaSMauro Carvalho Chehab 4154f38fcaSMauro Carvalho Chehab When the ``O_NONBLOCK`` flag is given, the system calls may return 4254f38fcaSMauro Carvalho Chehab ``EAGAIN`` error code when no data is available or when the device 4354f38fcaSMauro Carvalho Chehab driver is temporarily busy. 4454f38fcaSMauro Carvalho Chehab 4554f38fcaSMauro Carvalho Chehab Other flags have no effect. 4654f38fcaSMauro Carvalho Chehab 4754f38fcaSMauro Carvalho Chehab 4854f38fcaSMauro Carvalho ChehabDescription 4954f38fcaSMauro Carvalho Chehab=========== 5054f38fcaSMauro Carvalho Chehab 5154f38fcaSMauro Carvalho ChehabThis system call opens a named frontend device 5254f38fcaSMauro Carvalho Chehab(``/dev/dvb/adapter?/frontend?``) for subsequent use. Usually the first 5354f38fcaSMauro Carvalho Chehabthing to do after a successful open is to find out the frontend type 5454f38fcaSMauro Carvalho Chehabwith :ref:`FE_GET_INFO`. 5554f38fcaSMauro Carvalho Chehab 5654f38fcaSMauro Carvalho ChehabThe device can be opened in read-only mode, which only allows monitoring 5754f38fcaSMauro Carvalho Chehabof device status and statistics, or read/write mode, which allows any 5854f38fcaSMauro Carvalho Chehabkind of use (e.g. performing tuning operations.) 5954f38fcaSMauro Carvalho Chehab 6054f38fcaSMauro Carvalho ChehabIn a system with multiple front-ends, it is usually the case that 6154f38fcaSMauro Carvalho Chehabmultiple devices cannot be open in read/write mode simultaneously. As 6254f38fcaSMauro Carvalho Chehablong as a front-end device is opened in read/write mode, other open() 6354f38fcaSMauro Carvalho Chehabcalls in read/write mode will either fail or block, depending on whether 6454f38fcaSMauro Carvalho Chehabnon-blocking or blocking mode was specified. A front-end device opened 6554f38fcaSMauro Carvalho Chehabin blocking mode can later be put into non-blocking mode (and vice 6654f38fcaSMauro Carvalho Chehabversa) using the F_SETFL command of the fcntl system call. This is a 6754f38fcaSMauro Carvalho Chehabstandard system call, documented in the Linux manual page for fcntl. 6854f38fcaSMauro Carvalho ChehabWhen an open() call has succeeded, the device will be ready for use in 6954f38fcaSMauro Carvalho Chehabthe specified mode. This implies that the corresponding hardware is 7054f38fcaSMauro Carvalho Chehabpowered up, and that other front-ends may have been powered down to make 7154f38fcaSMauro Carvalho Chehabthat possible. 7254f38fcaSMauro Carvalho Chehab 7354f38fcaSMauro Carvalho Chehab 7454f38fcaSMauro Carvalho ChehabReturn Value 7554f38fcaSMauro Carvalho Chehab============ 7654f38fcaSMauro Carvalho Chehab 7754f38fcaSMauro Carvalho ChehabOn success :ref:`open() <frontend_f_open>` returns the new file descriptor. 7854f38fcaSMauro Carvalho ChehabOn error, -1 is returned, and the ``errno`` variable is set appropriately. 7954f38fcaSMauro Carvalho Chehab 8054f38fcaSMauro Carvalho ChehabPossible error codes are: 8154f38fcaSMauro Carvalho Chehab 8254f38fcaSMauro Carvalho Chehab 8354f38fcaSMauro Carvalho ChehabOn success 0 is returned, and :c:type:`ca_slot_info` is filled. 8454f38fcaSMauro Carvalho Chehab 8554f38fcaSMauro Carvalho ChehabOn error -1 is returned, and the ``errno`` variable is set 8654f38fcaSMauro Carvalho Chehabappropriately. 8754f38fcaSMauro Carvalho Chehab 8854f38fcaSMauro Carvalho Chehab.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| 8954f38fcaSMauro Carvalho Chehab 9054f38fcaSMauro Carvalho Chehab.. flat-table:: 9154f38fcaSMauro Carvalho Chehab :header-rows: 0 9254f38fcaSMauro Carvalho Chehab :stub-columns: 0 9354f38fcaSMauro Carvalho Chehab :widths: 1 16 9454f38fcaSMauro Carvalho Chehab 9554f38fcaSMauro Carvalho Chehab - - ``EPERM`` 9654f38fcaSMauro Carvalho Chehab - The caller has no permission to access the device. 9754f38fcaSMauro Carvalho Chehab 9854f38fcaSMauro Carvalho Chehab - - ``EBUSY`` 9954f38fcaSMauro Carvalho Chehab - The the device driver is already in use. 10054f38fcaSMauro Carvalho Chehab 10154f38fcaSMauro Carvalho Chehab - - ``EMFILE`` 10254f38fcaSMauro Carvalho Chehab - The process already has the maximum number of files open. 10354f38fcaSMauro Carvalho Chehab 10454f38fcaSMauro Carvalho Chehab - - ``ENFILE`` 10554f38fcaSMauro Carvalho Chehab - The limit on the total number of files open on the system has been 10654f38fcaSMauro Carvalho Chehab reached. 10754f38fcaSMauro Carvalho Chehab 10854f38fcaSMauro Carvalho Chehab 10954f38fcaSMauro Carvalho ChehabThe generic error codes are described at the 11054f38fcaSMauro Carvalho Chehab:ref:`Generic Error Codes <gen-errors>` chapter. 111