1 .. -*- coding: utf-8; mode: rst -*-
3 .. _video_function_calls:
17 This system call opens a named video device (e.g.
18 /dev/dvb/adapter0/video0) for subsequent use.
20 When an open() call has succeeded, the device will be ready for use. The
21 significance of blocking or non-blocking mode is described in the
22 documentation for functions where there is a difference. It does not
23 affect the semantics of the open() call itself. A device opened in
24 blocking mode can later be put into non-blocking mode (and vice versa)
25 using the F_SETFL command of the fcntl system call. This is a standard
26 system call, documented in the Linux manual page for fcntl. Only one
27 user can open the Video Device in O_RDWR mode. All other attempts to
28 open the device in this mode will fail, and an error-code will be
29 returned. If the Video Device is opened in O_RDONLY mode, the only
30 ioctl call that can be used is VIDEO_GET_STATUS. All other call will
35 int open(const char *deviceName, int flags);
48 - const char *deviceName
50 - Name of specific video device.
56 - A bit-wise OR of the following flags:
61 - O_RDONLY read-only access
66 - O_RDWR read/write access
71 - O_NONBLOCK open in non-blocking mode
76 - (blocking mode is the default)
92 - Device driver not loaded/available.
104 - Device or resource busy.
121 This system call closes a previously opened video device.
140 - File descriptor returned by a previous call to open().
156 - fd is not a valid open file descriptor.
167 This system call can only be used if VIDEO_SOURCE_MEMORY is selected
168 in the ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in
169 PES format, unless the capability allows other formats. If O_NONBLOCK
170 is not specified the function will block until buffer space is
171 available. The amount of data to be transferred is implied by count.
175 size_t write(int fd, const void *buf, size_t count);
190 - File descriptor returned by a previous call to open().
196 - Pointer to the buffer containing the PES data.
218 - Mode VIDEO_SOURCE_MEMORY not selected.
224 - Attempted to write more data than the internal buffer can hold.
230 - fd is not a valid open file descriptor.
241 This ioctl is for DVB devices only. To control a V4L2 decoder use the
242 V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
244 This ioctl call asks the Video Device to stop playing the current
245 stream. Depending on the input parameter, the screen can be blanked out
246 or displaying the last decoded frame.
250 int ioctl(fd, int request = VIDEO_STOP, boolean mode);
265 - File descriptor returned by a previous call to open().
271 - Equals VIDEO_STOP for this command.
277 - Indicates how the screen shall be handled.
282 - TRUE: Blank screen when stop.
287 - FALSE: Show last decoded frame.
292 On success 0 is returned, on error -1 and the ``errno`` variable is set
293 appropriately. The generic error codes are described at the
294 :ref:`Generic Error Codes <gen-errors>` chapter.
304 This ioctl is for DVB devices only. To control a V4L2 decoder use the
305 V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
307 This ioctl call asks the Video Device to start playing a video stream
308 from the selected source.
312 int ioctl(fd, int request = VIDEO_PLAY);
327 - File descriptor returned by a previous call to open().
333 - Equals VIDEO_PLAY for this command.
338 On success 0 is returned, on error -1 and the ``errno`` variable is set
339 appropriately. The generic error codes are described at the
340 :ref:`Generic Error Codes <gen-errors>` chapter.
350 This ioctl is for DVB devices only. To control a V4L2 decoder use the
351 V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
353 This ioctl call suspends the live video stream being played. Decoding
354 and playing are frozen. It is then possible to restart the decoding and
355 playing process of the video stream using the VIDEO_CONTINUE command.
356 If VIDEO_SOURCE_MEMORY is selected in the ioctl call
357 VIDEO_SELECT_SOURCE, the DVB subsystem will not decode any more data
358 until the ioctl call VIDEO_CONTINUE or VIDEO_PLAY is performed.
362 int ioctl(fd, int request = VIDEO_FREEZE);
377 - File descriptor returned by a previous call to open().
383 - Equals VIDEO_FREEZE for this command.
388 On success 0 is returned, on error -1 and the ``errno`` variable is set
389 appropriately. The generic error codes are described at the
390 :ref:`Generic Error Codes <gen-errors>` chapter.
400 This ioctl is for DVB devices only. To control a V4L2 decoder use the
401 V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
403 This ioctl call restarts decoding and playing processes of the video
404 stream which was played before a call to VIDEO_FREEZE was made.
408 int ioctl(fd, int request = VIDEO_CONTINUE);
423 - File descriptor returned by a previous call to open().
429 - Equals VIDEO_CONTINUE for this command.
434 On success 0 is returned, on error -1 and the ``errno`` variable is set
435 appropriately. The generic error codes are described at the
436 :ref:`Generic Error Codes <gen-errors>` chapter.
439 .. _VIDEO_SELECT_SOURCE:
446 This ioctl is for DVB devices only. This ioctl was also supported by the
447 V4L2 ivtv driver, but that has been replaced by the ivtv-specific
448 ``IVTV_IOC_PASSTHROUGH_MODE`` ioctl.
450 This ioctl call informs the video device which source shall be used for
451 the input data. The possible sources are demux or memory. If memory is
452 selected, the data is fed to the video device through the write command.
456 int ioctl(fd, int request = VIDEO_SELECT_SOURCE,
457 video_stream_source_t source);
472 - File descriptor returned by a previous call to open().
478 - Equals VIDEO_SELECT_SOURCE for this command.
482 - video_stream_source_t source
484 - Indicates which source shall be used for the Video stream.
489 On success 0 is returned, on error -1 and the ``errno`` variable is set
490 appropriately. The generic error codes are described at the
491 :ref:`Generic Error Codes <gen-errors>` chapter.
501 This ioctl call asks the Video Device to blank out the picture.
505 int ioctl(fd, int request = VIDEO_SET_BLANK, boolean mode);
520 - File descriptor returned by a previous call to open().
526 - Equals VIDEO_SET_BLANK for this command.
532 - TRUE: Blank screen when stop.
537 - FALSE: Show last decoded frame.
542 On success 0 is returned, on error -1 and the ``errno`` variable is set
543 appropriately. The generic error codes are described at the
544 :ref:`Generic Error Codes <gen-errors>` chapter.
547 .. _VIDEO_GET_STATUS:
554 This ioctl call asks the Video Device to return the current status of
559 int ioctl(fd, int request = VIDEO_GET_STATUS, struct video_status
575 - File descriptor returned by a previous call to open().
581 - Equals VIDEO_GET_STATUS for this command.
585 - struct video_status *status
587 - Returns the current status of the Video Device.
592 On success 0 is returned, on error -1 and the ``errno`` variable is set
593 appropriately. The generic error codes are described at the
594 :ref:`Generic Error Codes <gen-errors>` chapter.
597 .. _VIDEO_GET_FRAME_COUNT:
599 VIDEO_GET_FRAME_COUNT
600 =====================
604 This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders
605 this ioctl has been replaced by the ``V4L2_CID_MPEG_VIDEO_DEC_FRAME``
608 This ioctl call asks the Video Device to return the number of displayed
609 frames since the decoder was started.
613 int ioctl(int fd, int request = VIDEO_GET_FRAME_COUNT, __u64 *pts);
628 - File descriptor returned by a previous call to open().
634 - Equals VIDEO_GET_FRAME_COUNT for this command.
640 - Returns the number of frames displayed since the decoder was
646 On success 0 is returned, on error -1 and the ``errno`` variable is set
647 appropriately. The generic error codes are described at the
648 :ref:`Generic Error Codes <gen-errors>` chapter.
658 This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders
659 this ioctl has been replaced by the ``V4L2_CID_MPEG_VIDEO_DEC_PTS``
662 This ioctl call asks the Video Device to return the current PTS
667 int ioctl(int fd, int request = VIDEO_GET_PTS, __u64 *pts);
682 - File descriptor returned by a previous call to open().
688 - Equals VIDEO_GET_PTS for this command.
694 - Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 /
697 The PTS should belong to the currently played frame if possible,
698 but may also be a value close to it like the PTS of the last
699 decoded frame or the last PTS extracted by the PES parser.
704 On success 0 is returned, on error -1 and the ``errno`` variable is set
705 appropriately. The generic error codes are described at the
706 :ref:`Generic Error Codes <gen-errors>` chapter.
709 .. _VIDEO_GET_FRAME_RATE:
716 This ioctl call asks the Video Device to return the current framerate.
720 int ioctl(int fd, int request = VIDEO_GET_FRAME_RATE, unsigned int
736 - File descriptor returned by a previous call to open().
742 - Equals VIDEO_GET_FRAME_RATE for this command.
748 - Returns the framerate in number of frames per 1000 seconds.
753 On success 0 is returned, on error -1 and the ``errno`` variable is set
754 appropriately. The generic error codes are described at the
755 :ref:`Generic Error Codes <gen-errors>` chapter.
765 This ioctl is for DVB devices only. To get events from a V4L2 decoder
766 use the V4L2 :ref:`VIDIOC_DQEVENT` ioctl instead.
768 This ioctl call returns an event of type video_event if available. If
769 an event is not available, the behavior depends on whether the device is
770 in blocking or non-blocking mode. In the latter case, the call fails
771 immediately with errno set to EWOULDBLOCK. In the former case, the call
772 blocks until an event becomes available. The standard Linux poll()
773 and/or select() system calls can be used with the device file descriptor
774 to watch for new events. For select(), the file descriptor should be
775 included in the exceptfds argument, and for poll(), POLLPRI should be
776 specified as the wake-up condition. Read-only permissions are sufficient
781 int ioctl(fd, int request = VIDEO_GET_EVENT, struct video_event *ev);
796 - File descriptor returned by a previous call to open().
802 - Equals VIDEO_GET_EVENT for this command.
806 - struct video_event *ev
808 - Points to the location where the event, if any, is to be stored.
813 On success 0 is returned, on error -1 and the ``errno`` variable is set
814 appropriately. The generic error codes are described at the
815 :ref:`Generic Error Codes <gen-errors>` chapter.
828 - There is no event pending, and the device is in non-blocking mode.
834 - Overflow in event queue - one or more events were lost.
845 This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders
846 this ioctl has been replaced by the
847 :ref:`VIDIOC_DECODER_CMD` ioctl.
849 This ioctl commands the decoder. The ``video_command`` struct is a
850 subset of the ``v4l2_decoder_cmd`` struct, so refer to the
851 :ref:`VIDIOC_DECODER_CMD` documentation for
856 int ioctl(int fd, int request = VIDEO_COMMAND, struct video_command
872 - File descriptor returned by a previous call to open().
878 - Equals VIDEO_COMMAND for this command.
882 - struct video_command *cmd
884 - Commands the decoder.
889 On success 0 is returned, on error -1 and the ``errno`` variable is set
890 appropriately. The generic error codes are described at the
891 :ref:`Generic Error Codes <gen-errors>` chapter.
894 .. _VIDEO_TRY_COMMAND:
901 This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders
902 this ioctl has been replaced by the
903 :ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` ioctl.
905 This ioctl tries a decoder command. The ``video_command`` struct is a
906 subset of the ``v4l2_decoder_cmd`` struct, so refer to the
907 :ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` documentation
908 for more information.
912 int ioctl(int fd, int request = VIDEO_TRY_COMMAND, struct
928 - File descriptor returned by a previous call to open().
934 - Equals VIDEO_TRY_COMMAND for this command.
938 - struct video_command *cmd
940 - Try a decoder command.
945 On success 0 is returned, on error -1 and the ``errno`` variable is set
946 appropriately. The generic error codes are described at the
947 :ref:`Generic Error Codes <gen-errors>` chapter.
957 This ioctl returns the size and aspect ratio.
961 int ioctl(int fd, int request = VIDEO_GET_SIZE, video_size_t *size);
976 - File descriptor returned by a previous call to open().
982 - Equals VIDEO_GET_SIZE for this command.
988 - Returns the size and aspect ratio.
993 On success 0 is returned, on error -1 and the ``errno`` variable is set
994 appropriately. The generic error codes are described at the
995 :ref:`Generic Error Codes <gen-errors>` chapter.
998 .. _VIDEO_SET_DISPLAY_FORMAT:
1000 VIDEO_SET_DISPLAY_FORMAT
1001 ========================
1005 This ioctl call asks the Video Device to select the video format to be
1006 applied by the MPEG chip on the video.
1010 int ioctl(fd, int request = VIDEO_SET_DISPLAY_FORMAT,
1011 video_display_format_t format);
1026 - File descriptor returned by a previous call to open().
1032 - Equals VIDEO_SET_DISPLAY_FORMAT for this command.
1036 - video_display_format_t format
1038 - Selects the video format to be used.
1043 On success 0 is returned, on error -1 and the ``errno`` variable is set
1044 appropriately. The generic error codes are described at the
1045 :ref:`Generic Error Codes <gen-errors>` chapter.
1048 .. _VIDEO_STILLPICTURE:
1055 This ioctl call asks the Video Device to display a still picture
1056 (I-frame). The input data shall contain an I-frame. If the pointer is
1057 NULL, then the current displayed still picture is blanked.
1061 int ioctl(fd, int request = VIDEO_STILLPICTURE, struct
1062 video_still_picture *sp);
1077 - File descriptor returned by a previous call to open().
1083 - Equals VIDEO_STILLPICTURE for this command.
1087 - struct video_still_picture *sp
1089 - Pointer to a location where an I-frame and size is stored.
1094 On success 0 is returned, on error -1 and the ``errno`` variable is set
1095 appropriately. The generic error codes are described at the
1096 :ref:`Generic Error Codes <gen-errors>` chapter.
1099 .. _VIDEO_FAST_FORWARD:
1106 This ioctl call asks the Video Device to skip decoding of N number of
1107 I-frames. This call can only be used if VIDEO_SOURCE_MEMORY is
1112 int ioctl(fd, int request = VIDEO_FAST_FORWARD, int nFrames);
1127 - File descriptor returned by a previous call to open().
1133 - Equals VIDEO_FAST_FORWARD for this command.
1139 - The number of frames to skip.
1144 On success 0 is returned, on error -1 and the ``errno`` variable is set
1145 appropriately. The generic error codes are described at the
1146 :ref:`Generic Error Codes <gen-errors>` chapter.
1159 - Mode VIDEO_SOURCE_MEMORY not selected.
1163 .. _VIDEO_SLOWMOTION:
1170 This ioctl call asks the video device to repeat decoding frames N number
1171 of times. This call can only be used if VIDEO_SOURCE_MEMORY is
1176 int ioctl(fd, int request = VIDEO_SLOWMOTION, int nFrames);
1191 - File descriptor returned by a previous call to open().
1197 - Equals VIDEO_SLOWMOTION for this command.
1203 - The number of times to repeat each frame.
1208 On success 0 is returned, on error -1 and the ``errno`` variable is set
1209 appropriately. The generic error codes are described at the
1210 :ref:`Generic Error Codes <gen-errors>` chapter.
1223 - Mode VIDEO_SOURCE_MEMORY not selected.
1227 .. _VIDEO_GET_CAPABILITIES:
1229 VIDEO_GET_CAPABILITIES
1230 ======================
1234 This ioctl call asks the video device about its decoding capabilities.
1235 On success it returns and integer which has bits set according to the
1236 defines in section ??.
1240 int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, unsigned int
1256 - File descriptor returned by a previous call to open().
1262 - Equals VIDEO_GET_CAPABILITIES for this command.
1268 - Pointer to a location where to store the capability information.
1273 On success 0 is returned, on error -1 and the ``errno`` variable is set
1274 appropriately. The generic error codes are described at the
1275 :ref:`Generic Error Codes <gen-errors>` chapter.
1285 This ioctl selects which sub-stream is to be decoded if a program or
1286 system stream is sent to the video device.
1290 int ioctl(int fd, int request = VIDEO_SET_ID, int id);
1305 - File descriptor returned by a previous call to open().
1311 - Equals VIDEO_SET_ID for this command.
1317 - video sub-stream id
1322 On success 0 is returned, on error -1 and the ``errno`` variable is set
1323 appropriately. The generic error codes are described at the
1324 :ref:`Generic Error Codes <gen-errors>` chapter.
1337 - Invalid sub-stream id.
1341 .. _VIDEO_CLEAR_BUFFER:
1348 This ioctl call clears all video buffers in the driver and in the
1353 int ioctl(fd, int request = VIDEO_CLEAR_BUFFER);
1368 - File descriptor returned by a previous call to open().
1374 - Equals VIDEO_CLEAR_BUFFER for this command.
1379 On success 0 is returned, on error -1 and the ``errno`` variable is set
1380 appropriately. The generic error codes are described at the
1381 :ref:`Generic Error Codes <gen-errors>` chapter.
1384 .. _VIDEO_SET_STREAMTYPE:
1386 VIDEO_SET_STREAMTYPE
1387 ====================
1391 This ioctl tells the driver which kind of stream to expect being written
1392 to it. If this call is not used the default of video PES is used. Some
1393 drivers might not support this call and always expect PES.
1397 int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, int type);
1412 - File descriptor returned by a previous call to open().
1418 - Equals VIDEO_SET_STREAMTYPE for this command.
1429 On success 0 is returned, on error -1 and the ``errno`` variable is set
1430 appropriately. The generic error codes are described at the
1431 :ref:`Generic Error Codes <gen-errors>` chapter.
1434 .. _VIDEO_SET_FORMAT:
1441 This ioctl sets the screen format (aspect ratio) of the connected output
1442 device (TV) so that the output of the decoder can be adjusted
1447 int ioctl(fd, int request = VIDEO_SET_FORMAT, video_format_t
1463 - File descriptor returned by a previous call to open().
1469 - Equals VIDEO_SET_FORMAT for this command.
1473 - video_format_t format
1475 - video format of TV as defined in section ??.
1480 On success 0 is returned, on error -1 and the ``errno`` variable is set
1481 appropriately. The generic error codes are described at the
1482 :ref:`Generic Error Codes <gen-errors>` chapter.
1495 - format is not a valid video format.
1499 .. _VIDEO_SET_SYSTEM:
1506 This ioctl sets the television output format. The format (see section
1507 ??) may vary from the color format of the displayed MPEG stream. If the
1508 hardware is not able to display the requested format the call will
1513 int ioctl(fd, int request = VIDEO_SET_SYSTEM , video_system_t
1529 - File descriptor returned by a previous call to open().
1535 - Equals VIDEO_SET_FORMAT for this command.
1539 - video_system_t system
1541 - video system of TV output.
1546 On success 0 is returned, on error -1 and the ``errno`` variable is set
1547 appropriately. The generic error codes are described at the
1548 :ref:`Generic Error Codes <gen-errors>` chapter.
1561 - system is not a valid or supported video system.
1565 .. _VIDEO_SET_HIGHLIGHT:
1572 This ioctl sets the SPU highlight information for the menu access of a
1577 int ioctl(fd, int request = VIDEO_SET_HIGHLIGHT ,video_highlight_t
1593 - File descriptor returned by a previous call to open().
1599 - Equals VIDEO_SET_HIGHLIGHT for this command.
1603 - video_highlight_t *vhilite
1605 - SPU Highlight information according to section ??.
1610 On success 0 is returned, on error -1 and the ``errno`` variable is set
1611 appropriately. The generic error codes are described at the
1612 :ref:`Generic Error Codes <gen-errors>` chapter.
1622 This ioctl activates or deactivates SPU decoding in a DVD input stream.
1623 It can only be used, if the driver is able to handle a DVD stream.
1627 int ioctl(fd, int request = VIDEO_SET_SPU , video_spu_t *spu)
1642 - File descriptor returned by a previous call to open().
1648 - Equals VIDEO_SET_SPU for this command.
1654 - SPU decoding (de)activation and subid setting according to section
1660 On success 0 is returned, on error -1 and the ``errno`` variable is set
1661 appropriately. The generic error codes are described at the
1662 :ref:`Generic Error Codes <gen-errors>` chapter.
1675 - input is not a valid spu setting or driver cannot handle SPU.
1679 .. _VIDEO_SET_SPU_PALETTE:
1681 VIDEO_SET_SPU_PALETTE
1682 =====================
1686 This ioctl sets the SPU color palette.
1690 int ioctl(fd, int request = VIDEO_SET_SPU_PALETTE
1691 ,video_spu_palette_t *palette )
1706 - File descriptor returned by a previous call to open().
1712 - Equals VIDEO_SET_SPU_PALETTE for this command.
1716 - video_spu_palette_t *palette
1718 - SPU palette according to section ??.
1723 On success 0 is returned, on error -1 and the ``errno`` variable is set
1724 appropriately. The generic error codes are described at the
1725 :ref:`Generic Error Codes <gen-errors>` chapter.
1738 - input is not a valid palette or driver doesn’t handle SPU.
1749 This ioctl returns navigational information from the DVD stream. This is
1750 especially needed if an encoded stream has to be decoded by the
1755 int ioctl(fd, int request = VIDEO_GET_NAVI , video_navi_pack_t
1771 - File descriptor returned by a previous call to open().
1777 - Equals VIDEO_GET_NAVI for this command.
1781 - video_navi_pack_t *navipack
1783 - PCI or DSI pack (private stream 2) according to section ??.
1788 On success 0 is returned, on error -1 and the ``errno`` variable is set
1789 appropriately. The generic error codes are described at the
1790 :ref:`Generic Error Codes <gen-errors>` chapter.
1803 - driver is not able to return navigational information
1807 .. _VIDEO_SET_ATTRIBUTES:
1809 VIDEO_SET_ATTRIBUTES
1810 ====================
1814 This ioctl is intended for DVD playback and allows you to set certain
1815 information about the stream. Some hardware may not need this
1816 information, but the call also tells the hardware to prepare for DVD
1821 int ioctl(fd, int request = VIDEO_SET_ATTRIBUTE ,video_attributes_t
1837 - File descriptor returned by a previous call to open().
1843 - Equals VIDEO_SET_ATTRIBUTE for this command.
1847 - video_attributes_t vattr
1849 - video attributes according to section ??.
1854 On success 0 is returned, on error -1 and the ``errno`` variable is set
1855 appropriately. The generic error codes are described at the
1856 :ref:`Generic Error Codes <gen-errors>` chapter.
1869 - input is not a valid attribute setting.
1874 .. ------------------------------------------------------------------------------
1875 .. This file was automatically converted from DocBook-XML with the dbxml
1876 .. library (https://github.com/return42/sphkerneldoc). The origin XML comes
1877 .. from the linux kernel, refer to:
1879 .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
1880 .. ------------------------------------------------------------------------------
projects / deliverable / linux.git / blob