1. Function reference
Table of contents
V4L2 close() - Close a V4L2 device
V4L2 ioctl() - V4L2 device created
ioctl VIDIOC_CROPCAP - video cropping and scaling function information
ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER - read or write the hardware registry
ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD - execute encoder commands
ioctl VIDIOC_ENUMAUDIO - enumerate audio inputs
ioctl VIDIOC_ENUMAUDOUT - enumerate audio outputs
ioctl VIDIOC_ENUM_FMT - enumerate image formats
ioctl VIDIOC_ENUM_FRAMESIZES - enumeration form factors
ioctl VIDIOC_ENUM_FRAMEINTERVALS - enumeration frame intervals
ioctl VIDIOC_ENUMINPUT - enumerate video inputs
ioctl VIDIOC_ENUMOUTPUT - enumerate video outputs
ioctl VIDIOC_ENUMSTD - Enumerate supported video standards
ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO - Query or select the current audio input and its properties
ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT - Query or select the current audio output
ioctl VIDIOC_G_CHIP_IDENT – identifies the chip of the TV card
ioctl VIDIOC_G_CROP, VIDIOC_S_CROP - Get or set the current cropping rectangle
ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL - Get or set the value of the control
ioctl VIDIOC_G_ENC_INDEX - Get metadata about a compressed video stream
ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, VIDIOC_TRY_EXT_CTRLS - Get or set the value number of the control, try to control the value
ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF - Get or set parameters framebuffer override
ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT - get or set data format, test format
ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY - Get or set the tuner or RF modulator
ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT - Query or select the current video input
ioctl VIDIOC_G_JPEGCOMP，VIDIOC_S_JPEGCOMP -
ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR - modulator, get or set properties
ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT - Query or select the current video output
ioctl VIDIOC_G_PARM, VIDIOC_S_PARM - Get or set stream parameters
ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY - Query or require the priority of access associated with the file descriptor
ioctl VIDIOC_G_SLICED_VBI_CAP - Query the VBI function of the slice
ioctl VIDIOC_G_STD, VIDIOC_S_STD - Query or select the current input video standard
ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER - Get or set tuner properties
ioctl VIDIOC_LOG_STATUS - records driver status information
ioctl VIDIOC_OVERLAY - Start or stop video overlay
ioctl VIDIOC_QBUF, VIDIOC_DQBUF - communicate with driver buffers
ioctl VIDIOC_QUERYBUF - Query the status of a buffer
ioctl VIDIOC_QUERYCAP - Query device capabilities
ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU - enumerate control and menu control items
ioctl VIDIOC_QUERYSTD – identifies the video standard received by the current input
ioctl VIDIOC_REQBUFS - Initiates user pointer or memory mapped I/O
ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF - Start or stop streaming I/O
V4L2 mmap() - Maps device memory into the application's address space
V4L2 munmap() - Unmap device memory
V4L2 open() – the V4L2 device opened
V4L2 investigate() - wait for some event on a file descriptor
v4L2read() – Reads a V4L2 device
V4L2 select() - Synchronous I/O multiplexing
V4L2write() - writes to a V4L2 device
V4L2 close()
name
V4L2 shutdown - Shut down a V4L2 device
overview
#include <unistd.h>int close(int fd);
fd
The file descriptor returned by open().
illustrate
Turn off the device. That is, all I/O in the program is terminated and the resources associated with the file descriptor are released. But the data format parameters, current input or output, control values or other properties remain unchanged.
return value
The function returns 0 on success, -1 on failure and sets the appropriate errno. i.e. possible error codes:
EBADF
fd is not a valid open file descriptor.
V4L2 ioctl()
name
V4L2 -ioctl – Create a V4L2 device
overview
#include <sys/ioctl.h>int ioctl(int fd, int request, void *argp);
parameter
fd
The file descriptor returned by open().
Require
V4L2 IOCTL requires the code to be consistent with that defined in the videodev.h header file, such as VIDIOC_QUERYCAP.
argp
A pointer points to a function parameter, usually a structure.
illustrate
The ioctl() function is used to create V4L2 devices. The fd parameter must be an open file descriptor. IOCTL requires that all parameters be encoded, regardless of whether the parameter is an input, output or read/write parameter, and the parameter argp must be in bytes. Macros and well-defined V4L2 ioctl requirements are located in the videodev.h header file. Applications should use their own copy, excluding the version of the kernel source compiled on their system. All V4L2 ioctl requirements, i.e. their respective functions and parameters, are specified in Reference I, Function Reference.
return value
A successful ioctl() function will return 0 and will not reset the errno variable. If -1 is returned on failure, when the IOCTL will output or read/write parameters, it remains unchanged and the errno variable is set accordingly. See possible error codes below. General errors like EBADF EFAULT are not listed separately in the section discussing ioctl requirements.
Note that ioctl may return an undefined error code. Due to such errors it is possible for a driver restart application to terminate unexpectedly.
EBADF
fd is not a valid open file descriptor.
BUSY
This property cannot be changed immediately. This error code is usually returned when I/O is in progress or when the driver is multi-open and another process has locked ownership of it.
EFAULT
argp refers to an inaccessible memory area.
ENOTTY
fd is not associated with the character special device.
SINGLE CHOICE
The request or data argp points to is invalid. This is a very common error code. Please refer to the special ioctl requirements in Reference I. The reason is derived from the Function Reference.
ENOMEM
Not enough physical or virtual memory is available to complete the request.
ERANGE
The application attempted to establish a value outside the range of the controlling VIDIOC_S_CTRL ioctl.
ioctl VIDIOC_CROPCAP
name
VIDIOC_CROPCAP - Video crop and zoom function information
overview
int ioctl(int fd, int request, struct v4l2_cropcap *argp);
parameter
fd
The file descriptor returned by open().
ask
VIDIOC_CROPCAP
argp
illustrate
Applications use this function to query information about cropping limits, pixel aspects of an image, and calculated numerical ranges. They create a type field of the v4l2_cropcap structure with their respective buffer (stresm) type and call the VIDIOC_CROPCAP ioctl with a pointer to this structure. The driver complements the rest of the structure. The results are unchanged unless the video standard is switched. Remember that this switch is hidden when switching video input or output.
Table 1. struct v4l2_cropcap
enum v4l2_buf_type type
The application sets the type of data flow. These types are valid here only: V4L2_BUF_TYPE_VIDEO_CAPTURE, V4L2_BUF_TYPE_VIDEO_OUTPUT, V4L2_BUF_TYPE_VIDEO_OVERLAY, and custom (driver-defined) types when using code V4L2_BUF_TYPE_PRIVATE or higher.
struct v4l2_rect bounds
It is possible to define capture or output within a window, which may exclude, for example, horizontal and vertical blanking zones. The clipping rectangle cannot exceed these limits. Width and height are defined in pixels, and the driver writer is free to choose the origin and coordinate system units in the simulation domain.
struct v4l2_rect defrect
The default cropping rectangle, which should include the "full view". Assuming a pixel aspect ratio of 1/1, this might be, for example, a 640 × 480 rectangle in the center of the active image area for NTSC, or a 768 × 576 rectangle for PAL and SECAM. The same coordinate system is used for boundary definition.
struct v4l2_fract pixelaspect
In terms of pixels (y/x), when no scaling is applied, the actual sampling frequency ratio and frequency are required to get the square pixel frequency.
When the crop coordinates refer to square pixels, the driver sets the pixelaspect to 1/1. Other common values are NTSC for PAL and SECAM, 11/10 for 54/59 samples [ITU BT.601].
Table 2. struct v4l2_rect
__s32 left Horizontal offset of the top left corner of the rectangle, in pixels.
__s32 top Vertical offset of the top left corner of the rectangle, in pixels.
__s32 width The width of the rectangle, in pixels.
__s32 height The height of the rectangle, in pixels. Width and height cannot be negative, otherwise the field will be marked as the cause of the exception.
return value
Returns 0 on success, -1 on error, and the errno variable is set correctly:
SINGLE CHOICE
The structure v4l2_cropcap type is invalid or does not support ioctl. At this time video capture, output and overlay devices are not allowed, they must support VIDIOC_CROPCAP.
ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
name
VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER - read or write the hardware registry
overview
int ioctl(int fd, int request, struct v4l2_register *argp);
int ioctl(int fd, int request, const struct v4l2_register *argp);
parameter
fd
The file descriptor returned by open().
ask
VIDIOC_DBG_G_REGISTER，VIDIOC_DBG_S_REGISTER
argp
illustrate
Experimental: This is an experimental interface and may change in the future.
For debugging drivers, these IOCTLs allow test applications to directly access the hardware registry. Normal applications cannot use them.
Since writing or reading the registry may compromise system security, stability, and damage hardware, all ioctls require superuser privileges. Additionally, the Linux kernel must be compiled with the CONFIG_VIDEO_ADV_DEBUG option to enable these IOCTLs.
To write a registry application, you must initialize all fields of a structure v4l2_register and call VIDIOC_DBG_S_REGISTER with a pointer to this structure. The match_type and match_chip fields select a chip on the TV card. This registry field specifies a registry number. The Val field value is written to the registry.
Applications that want to read the registry must initialize the match_type, match_chip, and REG fields and call VIDIOC_DBG_G_REGISTER with a pointer to this structure. If successful, the driver stores the value from the registry in the Val field. On failure, the structure remains unchanged.
When match_type is V4L2_CHIP_MATCH_HOST, match_chip selects the nth nonI2C chip on the TV card. The driver might understand match_chip as a random ID, but we don't understand it that way. The number zero always selects the master chip, i.e. the chip is connected to the PCI bus. You can find out which chips provide the VIDIOC_G_CHIP_IDENT ioctl.
When match_type is V4L2_CHIP_MATCH_I2C_DRIVER, as defined in the linux/i2c-id.h header file, match_chip contains a driver ID, for example I2C_DRIVERID_SAA7127 will match any chip supported by the saa7127 driver, regardless of its I2C bus address. These IOCTL effects are undefined when multiple chips supported by the same driver are running. In addition, you can use VIDIOC_G_CHIP_IDENTioctl to find out the running I2C chip.
When match_type is V4L2_CHIP_MATCH_I2C_ADDR, match_chip uses the 7-bit I2C bus address to select a chip.
Success is not guaranteed: due to a bug in the Linux I2C bus driver, these IOCTLs may be returned successfully without actually reading or writing a registry. To find the most likely failure, we recommend a VIDIOC_G_CHIP_IDENT command to confirm that the selected I2C chip is running.
These IOCTLs are selective and not all drivers support them. However, when a driver supports these IOCTLs it must also support VIDIOC_G_CHIP_IDENT. Instead it may support VIDIOC_G_CHIP_IDENT but not these IOCTLs.
VIDIOC_DBG_G_REGISTER and VIDIOC_DBG_S_REGISTER will be introduced in Linux 2.6.21.
We recommend using the V4L2-dbg utility to end calls to these IOCTLs directly. This can be seen from the LinuxTV v41-DVB library; visit http://linuxtv.org/repo/ for instructions.
Table 1. struct v4l2_register
__u32 match_type See Table 2 for a table of possible types.
__u32 match_chip This code matches the chip and is interpreted and executed according to the match_type field.
__u64 reg A registration code.
__u64 val This value is read from or written to the registry.
Table 2. Chip Match Types
V4L2_CHIP_MATCH_HOST 0 matches n chips on the card, 0 is the host chip. Does not match I2C chip.
V4L2_CHIP_MATCH_I2C_DRIVER 1 Matches the I2C chip with the driver's ID in the linux/i2c-id.h header file.
V4L2_CHIP_MATCH_I2C_ADDR 2 matches the 7-bit I2C bus address chip.
return value
Returns 0 on success, -1 on error, and the errno variable is set accordingly:
SINGLE CHOICE
The driver does not support this IOCTL, or the kernel was not compiled with the CONFIG_VIDEO_ADV_DEBUG option, or the match_type is invalid, or the selected chip or registry does not exist.
ReturnEPERM
Insufficient permissions. Root privileges are required to execute these IOCTLs.
ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
name
VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD - execute encoder commands
Introduction
int ioctl(int fd, int request, struct v4l2_encoder_cmd *argp);
parameter
fd
The file descriptor returned by open().
ask
VIDIOC_ENCODER_CMD，VIDIOC_TRY_ENCODER_CMD
argp
illustrate
Experimental: This is an experimental interface and may change in the future.
These IOCTLs control audio/video (usually MPEG-) encoders. VIDIOC_ENCODER_CMD sends a command to the encoder. VIDIOC_TRY_ENCODER_CMD can be used to try a command without actually executing the command.
To send a command the program must initialize all fields of a struct v4l2_encoder_cmd and call VIDIOC_ENCODER_CMD or VIDIOC_TRY_ENCODER_CMD with a pointer to the structure.
The cmd field must contain the command code. These flag fields are generally only used for stop commands and contain one byte: If the V4L2_ENC_CMD_STOP_AT_GOP_END flag is set, encoding will continue until the end of the current group of pictures, otherwise it will stop immediately.
If the encoder has not started yet, a read() call will send it a start command. After executing the STOP command, the read() call reads the remaining data buffered by the driver. When the buffer is empty, read() will return zero and the next read() call will restart the encoder.
A close() call sends a stop command to the encoder and all buffered data will be cleared.
These IOCTLs are optional and not all drivers support them. They will be introduced in Linux 2.6.21.
Table 1. struct v4l2_encoder_cmd
__u32 cmd encoder command, see Table 2.
__u32 flags flag command, see Table 3. If no command is defined with this flag, drivers and applications must set this field to zero.
__u32 data[8] is reserved for future extension. Drivers and applications must set the array to zero.
Table 2. Encoder Commands
V4L2_ENC_CMD_START 0 Start running the encoder. When the encoder is already running or paused, this command does nothing. This command does not define any flags. V4L2_ENC_CMD_STOP 1 Stops the encoder. When the V4L2_ENC_CMD_STOP_AT_GOP_END flag is set, encoding will continue until the end of the current group of pictures, otherwise, encoding will stop immediately. When the encoder has been stopped, this command does nothing.
V4L2_ENC_CMD_PAUSE 2 Pauses the encoder. When the encoder has not started, the driver will return an EPERM error code. When the encoder is already paused, this command does nothing. This command does not define any flags.
V4L2_ENC_CMD_RESUME 3 Resume encoding command after pause. When the encoder has not started, the driver will return an EPERM error code. When the encoder is already running, this command does nothing. This command does not define any flags.
Table 3. Encoder Command Flags
V4L2_ENC_CMD_STOP_AT_GOP_END 0x0001 Stop encoding the current image group instead of ending immediately.
return value
Returns 0 on success, -1 on error, and the errno variable is set correctly:
SINGLE CHOICE
The driver does not support this IOCTL, or the cmd field is invalid.
Upper
When the encoder is not running, the application sends a pause or resume command.
ioctl VIDIOC_ENUMAUDIO
name
VIDIOC_ENUMAUDIO - enumerate audio inputs
Introduction
int ioctl(int fd, int request, struct v4l2_audio *argp);
parameter
fd
The file descriptor returned by open().
ask
VIDIOC_ENUMAUDIO
argp
illustrate
To query the properties of the audio input the application should initialize a structure v4l2_audio holding the index fields of the array and zero and call the VIDIOC_ENUMAUDIO ioctl with this structure pointer. The driver fills in the rest of the structure or returns an EINVAL error code when the index is out of range. Enumeration of all audio input applications shall start at index zero and increment by EINVAL returned by the driver until one.
See the structure described in v4l2_audio's ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO(2).
return value
Returns 0 on success, -1 on error, and the errno variable is set correctly:
SINGLE CHOICE
The audio input number is out of bounds, or there is no audio input at all, and this IOCTL does not support audio input.
ioctl VIDIOC_ENUMAUDOUT
name
VIDIOC_ENUMAUDOUT - enum audio output
Introduction
int ioctl(int fd, int request, struct v4l2_audioout *argp);
parameter
fd
The file descriptor returned by open().
Require
VIEWER_ENUMAUDOUT
argp
illustrate
To query the properties of the audio output application initialize the index field and zero out a reserved array of v4l2_audioout structures, and call the VIDIOC_G_AUDOUT ioctl on this structure with a pointer. When the index is out of range, the driver will stop the structure or return an EINVAL error code. To enumerate all audio outputs, the application shall start at index zero and then increment until the driver returns EINVAL.
Note that the connector on the TV card loops back the received audio signal, in the sense that the sound card has no audio output.
See the structure v4l2_audioout's ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT(2) that describes the structure.
return value
Returns 0 on success, -1 on error, and the errno variable is set correctly:
SINGLE CHOICE
The number of audio outputs is out of range, or there is no audio output at all and the IOCTL does not support audio output.