7.71. V4L2 read()

7.71.1. 名稱

v4l2-read - 從V4L2裝置讀取

7.71.2. 概要

#include <unistd.h>

ssize_t read(int fd, void *buf, size_t count)

7.71.3. 引數

fd

open()返回的檔案描述符。

buf

要填充的緩衝區

count

要讀取的最大位元組數

7.71.4. 描述

read()嘗試從檔案描述符fd讀取最多count個位元組到從buf開始的緩衝區中。緩衝區的data佈局在相應的裝置介面部分討論，參見 ##。如果count為零，read()返回零並且沒有其他結果。如果count大於SSIZE_MAX，則結果未指定。無論count值如何，每次read()呼叫最多提供一幀（兩個欄位）的資料。

預設情況下，read()會阻塞直到有資料可用。當O_NONBLOCK標誌被賦予open()函式時，如果沒有資料可用，它會立即返回並顯示EAGAIN錯誤程式碼。 select()或poll()函式始終可用於暫停執行，直到資料變為可用。所有支援read()函式的驅動程式也必須支援select()和poll()。

驅動程式可以使用單個或多個緩衝區以不同的方式實現讀取功能，並在內部緩衝區填滿後丟棄最舊或最新的幀。

read()永遠不會返回正在填充的緩衝區的“快照”。使用單個緩衝區時，驅動程式將在應用程式開始讀取緩衝區時停止捕獲，直到讀取完成。因此，只有垂直消隱間隔期間可用於讀取，或者捕獲速率必須低於影片標準的標稱幀速率。

當在有效影像期間或分隔頂部和底部場的垂直消隱期間呼叫時，read()的行為取決於丟棄策略。丟棄最舊幀的驅動程式會持續捕獲到內部緩衝區中，不斷覆蓋先前未讀取的幀，並在read()呼叫時接收到的幀完成後返回該幀。

丟棄最新幀的驅動程式會停止捕獲，直到下一次read()呼叫。在read()時接收的幀將被丟棄，而是返回以下幀。同樣，這意味著捕獲速率降低到標稱幀速率的一半或更低。此模型的一個示例是bttv驅動程式的影片讀取模式，當呼叫read()時啟動到使用者記憶體的DMA，並在DMA完成時返回。

在多緩衝區模型中，驅動程式維護一個內部緩衝區環，自動前進到下一個空閒緩衝區。這允許應用程式在可以足夠快地清空緩衝區時進行連續捕獲。同樣，當驅動程式耗盡空閒緩衝區時，該行為取決於丟棄策略。

應用程式可以使用VIDIOC_G_PARM和VIDIOC_S_PARM ioctl獲取和設定驅動程式內部使用的緩衝區數量。 但是，它們是可選的。丟棄策略不會被報告，也無法更改。有關最低要求，請參見介面。

7.71.5. 返回值

成功時，返回讀取的位元組數。 如果此數字小於請求的位元組數或一幀所需的資料量，則不是錯誤。 例如，發生這種情況可能是因為read()被訊號中斷。 出錯時，返回 -1，並適當地設定errno變數。 在這種情況下，下一次讀取將從新幀的開頭開始。 可能的錯誤程式碼是

EAGAIN

已使用 O_NONBLOCK 選擇了非阻塞 I/O，並且沒有可立即讀取的資料。

EBADF

fd不是有效的檔案描述符，或者未開啟以供讀取，或者該程序已經打開了最大數量的檔案。

EBUSY

驅動程式不支援多個讀取流，並且裝置已在使用中。

EFAULT

buf引用了無法訪問的記憶體區域。

EINTR

在讀取任何資料之前，該呼叫被訊號中斷。

EIO

I/O錯誤。 這表明存在一些硬體問題或與遠端裝置（USB攝像頭等）通訊失敗。

EINVAL

此驅動程式、此裝置或通常此型別的裝置不支援read()函式。