[mirror_ubuntu-artful-kernel.git] / Documentation / media / uapi / v4l / func-write.rst

.. -*- coding: utf-8; mode: rst -*-

.. _func-write:

************
V4L2 write()
************

Name
====

v4l2-write - Write to a V4L2 device


Synopsis
========

.. code-block:: c

    #include <unistd.h>


.. cpp:function:: ssize_t write( int fd, void *buf, size_t count )


Arguments
=========

``fd``
    File descriptor returned by :ref:`open() <func-open>`.

``buf``
``count``


Description
===========

:ref:`write() <func-write>` writes up to ``count`` bytes to the device
referenced by the file descriptor ``fd`` from the buffer starting at
``buf``. When the hardware outputs are not active yet, this function
enables them. When ``count`` is zero, :ref:`write() <func-write>` returns 0
without any other effect.

When the application does not provide more data in time, the previous
video frame, raw VBI image, sliced VPS or WSS data is displayed again.
Sliced Teletext or Closed Caption data is not repeated, the driver
inserts a blank line instead.


Return Value
============

On success, the number of bytes written are returned. Zero indicates
nothing was written. On error, -1 is returned, and the ``errno``
variable is set appropriately. In this case the next write will start at
the beginning of a new frame. Possible error codes are:

EAGAIN
    Non-blocking I/O has been selected using the
    :ref:`O_NONBLOCK <func-open>` flag and no buffer space was
    available to write the data immediately.

EBADF
    ``fd`` is not a valid file descriptor or is not open for writing.

EBUSY
    The driver does not support multiple write streams and the device is
    already in use.

EFAULT
    ``buf`` references an inaccessible memory area.

EINTR
    The call was interrupted by a signal before any data was written.

EIO
    I/O error. This indicates some hardware problem.

EINVAL
    The :ref:`write() <func-write>` function is not supported by this driver,
    not on this device, or generally not on this type of device.
Commit	Line	Data
5377d91f MH	1	.. -- coding: utf-8; mode: rst --
	2
	3	.. _func-write:
	4
	5	************
	6	V4L2 write()
	7	************
	8
15e7d615	9	Name
586027ce	10	====
5377d91f	11
586027ce	12	v4l2-write - Write to a V4L2 device
5377d91f	13
15e7d615 MCC	14
15e7d615 MCC	15	Synopsis
5377d91f MH	16	========
	17
	18	.. code-block:: c
	19
	20	#include <unistd.h>
	21
	22
b7e67f6c	23	.. cpp:function:: ssize_t write( int fd, void *buf, size_t count )
5377d91f	24
586027ce	25
15e7d615	26	Arguments
5377d91f MH	27	=========
	28
	29	``fd``
	30	File descriptor returned by :ref:`open() <func-open>`.
	31
	32	``buf``
	33	``count``
	34
	35
15e7d615	36	Description
5377d91f MH	37	===========
5377d91f MH	38
760c7010	39	:ref:`write() <func-write>` writes up to ``count`` bytes to the device
5377d91f MH	40	referenced by the file descriptor ``fd`` from the buffer starting at
5377d91f MH	41	``buf``. When the hardware outputs are not active yet, this function
760c7010	42	enables them. When ``count`` is zero, :ref:`write() <func-write>` returns 0
5377d91f MH	43	without any other effect.
	44
	45	When the application does not provide more data in time, the previous
	46	video frame, raw VBI image, sliced VPS or WSS data is displayed again.
	47	Sliced Teletext or Closed Caption data is not repeated, the driver
	48	inserts a blank line instead.
	49
	50
15e7d615	51	Return Value
5377d91f MH	52	============
	53
	54	On success, the number of bytes written are returned. Zero indicates
	55	nothing was written. On error, -1 is returned, and the ``errno``
	56	variable is set appropriately. In this case the next write will start at
	57	the beginning of a new frame. Possible error codes are:
	58
	59	EAGAIN
	60	Non-blocking I/O has been selected using the
	61	:ref:`O_NONBLOCK <func-open>` flag and no buffer space was
	62	available to write the data immediately.
	63
	64	EBADF
	65	``fd`` is not a valid file descriptor or is not open for writing.
	66
	67	EBUSY
	68	The driver does not support multiple write streams and the device is
	69	already in use.
	70
	71	EFAULT
	72	``buf`` references an inaccessible memory area.
	73
	74	EINTR
	75	The call was interrupted by a signal before any data was written.
	76
	77	EIO
	78	I/O error. This indicates some hardware problem.
	79
	80	EINVAL
760c7010	81	The :ref:`write() <func-write>` function is not supported by this driver,
5377d91f	82	not on this device, or generally not on this type of device.