Merge branch 'linus' of git://git.kernel.org/pub/scm/linux/kernel/git/herbert/crypto-2.6
[linux/fpc-iii.git] / Documentation / media / uapi / dvb / frontend_f_open.rst
blob690eb375bdc1eeb77c063fa7d3be2fcdb9a466e7
1 .. -*- coding: utf-8; mode: rst -*-
3 .. _frontend_f_open:
5 *******************
6 DVB frontend open()
7 *******************
9 Name
10 ====
12 fe-open - Open a frontend device
15 Synopsis
16 ========
18 .. code-block:: c
20     #include <fcntl.h>
23 .. c:function:: int open( const char *device_name, int flags )
24     :name: dvb-fe-open
26 Arguments
27 =========
29 ``device_name``
30     Device to be opened.
32 ``flags``
33     Open flags. Access can either be ``O_RDWR`` or ``O_RDONLY``.
35     Multiple opens are allowed with ``O_RDONLY``. In this mode, only
36     query and read ioctls are allowed.
38     Only one open is allowed in ``O_RDWR``. In this mode, all ioctls are
39     allowed.
41     When the ``O_NONBLOCK`` flag is given, the system calls may return
42     ``EAGAIN`` error code when no data is available or when the device
43     driver is temporarily busy.
45     Other flags have no effect.
48 Description
49 ===========
51 This system call opens a named frontend device
52 (``/dev/dvb/adapter?/frontend?``) for subsequent use. Usually the first
53 thing to do after a successful open is to find out the frontend type
54 with :ref:`FE_GET_INFO`.
56 The device can be opened in read-only mode, which only allows monitoring
57 of device status and statistics, or read/write mode, which allows any
58 kind of use (e.g. performing tuning operations.)
60 In a system with multiple front-ends, it is usually the case that
61 multiple devices cannot be open in read/write mode simultaneously. As
62 long as a front-end device is opened in read/write mode, other open()
63 calls in read/write mode will either fail or block, depending on whether
64 non-blocking or blocking mode was specified. A front-end device opened
65 in blocking mode can later be put into non-blocking mode (and vice
66 versa) using the F_SETFL command of the fcntl system call. This is a
67 standard system call, documented in the Linux manual page for fcntl.
68 When an open() call has succeeded, the device will be ready for use in
69 the specified mode. This implies that the corresponding hardware is
70 powered up, and that other front-ends may have been powered down to make
71 that possible.
74 Return Value
75 ============
77 On success :ref:`open() <frontend_f_open>` returns the new file descriptor.
78 On error, -1 is returned, and the ``errno`` variable is set appropriately.
80 Possible error codes are:
82 EACCES
83     The caller has no permission to access the device.
85 EBUSY
86     The the device driver is already in use.
88 ENXIO
89     No device corresponding to this device special file exists.
91 ENOMEM
92     Not enough kernel memory was available to complete the request.
94 EMFILE
95     The process already has the maximum number of files open.
97 ENFILE
98     The limit on the total number of files open on the system has been
99     reached.
101 ENODEV
102     The device got removed.