cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

frontend_f_open.rst (3015B)


      1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
      2.. c:namespace:: DTV.fe
      3
      4.. _frontend_f_open:
      5
      6***************************
      7Digital TV frontend open()
      8***************************
      9
     10Name
     11====
     12
     13fe-open - Open a frontend device
     14
     15Synopsis
     16========
     17
     18.. code-block:: c
     19
     20    #include <fcntl.h>
     21
     22.. c:function:: int open( const char *device_name, int flags )
     23
     24Arguments
     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
     45Description
     46===========
     47
     48This system call opens a named frontend device
     49(``/dev/dvb/adapter?/frontend?``) for subsequent use. Usually the first
     50thing to do after a successful open is to find out the frontend type
     51with :ref:`FE_GET_INFO`.
     52
     53The device can be opened in read-only mode, which only allows monitoring
     54of device status and statistics, or read/write mode, which allows any
     55kind of use (e.g. performing tuning operations.)
     56
     57In a system with multiple front-ends, it is usually the case that
     58multiple devices cannot be open in read/write mode simultaneously. As
     59long as a front-end device is opened in read/write mode, other open()
     60calls in read/write mode will either fail or block, depending on whether
     61non-blocking or blocking mode was specified. A front-end device opened
     62in blocking mode can later be put into non-blocking mode (and vice
     63versa) using the F_SETFL command of the fcntl system call. This is a
     64standard system call, documented in the Linux manual page for fcntl.
     65When an open() call has succeeded, the device will be ready for use in
     66the specified mode. This implies that the corresponding hardware is
     67powered up, and that other front-ends may have been powered down to make
     68that possible.
     69
     70Return Value
     71============
     72
     73On success :c:func:`open()` returns the new file descriptor.
     74On error, -1 is returned, and the ``errno`` variable is set appropriately.
     75
     76Possible error codes are:
     77
     78On success 0 is returned, and :c:type:`ca_slot_info` is filled.
     79
     80On error -1 is returned, and the ``errno`` variable is set
     81appropriately.
     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 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
    103The generic error codes are described at the
    104:ref:`Generic Error Codes <gen-errors>` chapter.