Documentation/media/uapi/cec/cec-func-open.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _cec-func-open:
   4
   5 **********
   6 cec open()
   7 **********
   8
   9 Name
  10 ====
  11
  12 cec-open - Open a cec device
  13
  14 Synopsis
  15 ========
  16
  17 .. code-block:: c
  18
  19     #include <fcntl.h>
  20
  21
  22 .. c:function:: int open( const char *device_name, int flags )
  23    :name: cec-open
  24
  25
  26 Arguments
  27 =========
  28
  29 ``device_name``
  30     Device to be opened.
  31
  32 ``flags``
  33     Open flags. Access mode must be ``O_RDWR``.
  34
  35     When the ``O_NONBLOCK`` flag is given, the
  36     :ref:`CEC_RECEIVE <CEC_RECEIVE>` and :c:func:`CEC_DQEVENT` ioctls
  37     will return the ``EAGAIN`` error code when no message or event is available, and
  38     ioctls :ref:`CEC_TRANSMIT <CEC_TRANSMIT>`,
  39     :ref:`CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` and
  40     :ref:`CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
  41     all return 0.
  42
  43     Other flags have no effect.
  44
  45
  46 Description
  47 ===========
  48
  49 .. note::
  50
  51    This documents the proposed CEC API. This API is not yet finalized
  52    and is currently only available as a staging kernel module.
  53
  54 To open a cec device applications call :c:func:`open()` with the
  55 desired device name. The function has no side effects; the device
  56 configuration remain unchanged.
  57
  58 When the device is opened in read-only mode, attempts to modify its
  59 configuration will result in an error, and ``errno`` will be set to
  60 EBADF.
  61
  62
  63 Return Value
  64 ============
  65
  66 :c:func:`open()` returns the new file descriptor on success. On error,
  67 -1 is returned, and ``errno`` is set appropriately. Possible error codes
  68 include:
  69
  70 ``EACCES``
  71     The requested access to the file is not allowed.
  72
  73 ``EMFILE``
  74     The process already has the maximum number of files open.
  75
  76 ``ENFILE``
  77     The system limit on the total number of open files has been reached.
  78
  79 ``ENOMEM``
  80     Insufficient kernel memory was available.
  81
  82 ``ENXIO``
  83     No device corresponding to this device special file exists.