32.3. 客戶端接口 · PostgreSQL 中文文檔 9.3

# 32.3\. 客戶端接口本節描述PostgreSQL的libpq客戶端接口庫提供來訪問大對象的設施。 PostgreSQL大對象接口是對Unix文件系統的模仿，有仿真的`open`，`read`，`write`， `lseek`等。使用這些函數的所有大對象操作_必須_在一個SQL事務塊中發生，由于大對象的文件描述符對事務的整段時間內是唯一有效的。如果在執行這些函數的任何一個發生錯誤的時候，該函數將返回一個不可能的值，通常為0或1。一個描述該錯誤的消息存儲在連接對象中，并且可以用`PQerrorMessage`檢索。客戶端應用程序使用包含`libpq/libpq-fs.h`頭文件的這些函數，并且可以與libpq庫連接。 ## 32.3.1\. 創建大對象函數 ``` Oid lo_creat(PGconn *conn, int mode); ``` 創建一個新的大對象。返回值是賦予新大對象的OID，或者是失敗的時候是`InvalidOid`（零）。在PostgreSQL 8.1里，沒有再使用`_mode_`，并且它被忽略；不過，為了和早期的版本向下兼容，我們最好將其設置為`INV_READ`, `INV_WRITE`, 或者`INV_READ` `|` `INV_WRITE`。（這些符號常量在頭文件`libpq/libpq-fs.h`里定義。）例如： ``` inv_oid = lo_creat(conn, INV_READ|INV_WRITE); ``` 函數 ``` Oid lo_create(PGconn *conn, Oid lobjId); ``` 也創建一個新的大對象。要賦予數值的OID可以用`_lobjId_`聲明；如果這么做，那么在該OID已經被其他大對象使用的情況下就會生成錯誤。如果`_lobjId_`為`InvalidOid`（零），那么`lo_create`賦予一個未用的OID，這個和`lo_creat`的行為一致。）返回值是賦予新的大對象的OID，或者是失敗情況下的`InvalidOid`（零）。 `lo_create`函數是PostgreSQL 8.1里面新增加的；如果在老的服務器上運行這個函數，它會失敗并返回`InvalidOid`。例子： ``` inv_oid = lo_create(conn, desired_oid); ``` ## 32.3.2\. 輸入大對象要把一個操作系統文件輸入成為大對象，調用 ``` Oid lo_import(PGconn *conn, const char *filename); ``` `_filename_`參數指明要被輸入成為大對象的操作系統文件路徑名。返回值是賦予新大對象的OID。如果失敗則返回`InvalidOid`（零）。請注意這個文件是由客戶端接口庫讀取的，而不是服務器端；因此它必須存在于客戶端文件系統上并且可以被客戶應用讀取。函數 ``` Oid lo_import_with_oid(PGconn *conn, const char *filename, Oid lobjId); ``` 也能引入一個新的大對象。要賦予數值的OID可以用`_lobjId_`聲明；如果這么做，那么在該OID已經被其他大對象使用的情況下就會生成錯誤。如果`_lobjId_`為`InvalidOid`（零），那么`lo_import_with_oid`賦予一個未用的OID，這個和`lo_import`的行為一致。）返回值是賦予新的大對象的OID，或者是失敗情況下的`InvalidOid`（零）。 `lo_import_with_oid`是PostgreSQL 8.4里面新增加的，并且內部調用`lo_create`(8.1新增的)，如果此功能在8.0或之前運行這個函數，它會失敗并返回`InvalidOid`。 ## 32.3.3\. 輸出大對象要把一個大對象輸出為操作系統文件，調用 ``` int lo_export(PGconn *conn, Oid lobjId, const char *filename); ``` `lobjId`參數指明要輸出的大對象OID， `filename`參數指明操作系統文件的路徑名。請注意這個文件是由客戶端接口庫寫入的，而不是服務器端。成功時返回1，失敗時返回-1。 ## 32.3.4\. 打開一個現有的大對象要打開一個現存的大對象讀寫，調用 ``` int lo_open(PGconn *conn, Oid lobjId, int mode); ``` 參數`lobjId`指明要打開的大對象的OID（對象標識）。 `mode`位控制該對象是用于只讀（`INV_READ`），只寫（`INV_WRITE`）還是讀寫。（這些符號常量在頭文件`libpq/libpq-fs.h`.里定義。） `lo_open`返回非負大對象標識用于以后的`lo_read`， `lo_write`，`lo_lseek`， `lo_lseek64`，`lo_tell`， `lo_tell64`，`lo_truncate`， `lo_truncate64`和`lo_close`。這個描述符只是在當前事務中有效。失敗的時候，返回-1。服務器目前并不區分`INV_WRITE`和`INV_READ` `|` `INV_WRITE`模式：可以從這些任一模式中讀取描述符。但與`INV_READ`有明顯的不同：對于`INV_READ`，你不能寫入描述符，并且從其中讀取的數據將反映執行`lo_open`的時候事務快照對應的大對象的數據，而不會考慮本次事務后面寫入的或者其他事務寫入的數據。從一個用`INV_WRITE`打開的描述符里面讀取的數據反映所有其他已經提交的事務和當前事務的寫操作寫入的大對象的數據。這個行為類似普通SQL語句`SELECT`在事務模式中 `REPEATABLE READ`對比`READ COMMITTED`的行為。例子： ``` inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE); ``` ## 32.3.5\. 向大對象中寫數據函數 ``` int lo_write(PGconn *conn, int fd, const char *buf, size_t len); ``` 從`buf`中（這個大小必須是`len`）向大對象描述符`fd`寫入`len`字節。 `fd`參數必須是前面的一個`lo_open`調用的返回。返回實際寫入的字節數（當前實現過程中，它總是等于`len`，除非有錯誤）。出錯時，返回值是-1。盡管`len`參數被聲明為`size_t`，這個函數將拒絕長度值大于`INT_MAX`。實踐中，最好以兆字節傳輸塊中數據。 ## 32.3.6\. 從大對象中讀取數據函數 ``` int lo_read(PGconn *conn, int fd, char *buf, size_t len); ``` 從大對象描述符`fd`中讀取`len` 字節數據到`buf`中(大小必須是`len`)。 `fd`參數必須是前面的一個`lo_open`調用的返回。返回實際讀取的字節數。如果大對象的結尾達到第一，則小于`len`。出錯時，返回值是-1。盡管`len`參數被聲明為`size_t`，這個函數將拒絕長度值大于`INT_MAX`。實踐中，最好以兆字節傳輸塊中數據。 ## 32.3.7\. 大對象中查找要改變與一個大對象描述符相關的讀寫位置，調用 ``` int lo_lseek(PGconn *conn, int fd, int offset, int whence); ``` 這個過程把當前`fd`代表的大對象描述符位置指針移動到`offset`指明的新的位置。參數`whence`的合法的取值是`SEEK_SET`（從對象開頭開始找）， `SEEK_CUR`（從當前位置開始找），和`SEEK_END`（從對象結尾開始找）。返回值是新位置指針，如果出錯為-1。當處理可能超過2GB的大對象時，而是使用： ``` pg_int64 lo_lseek64(PGconn *conn, int fd, pg_int64 offset, int whence); ``` 這個函數有`lo_lseek`同樣的操作，但是它可以接受`offset`大于2GB和/或者傳遞大于2GB的一個結果。注意如果新的位置指針大于2GB，那么`lo_lseek`將失敗。 `lo_lseek64`是PostgreSQL 9.3中新的。如果這個函數運行在一個舊的服務器版本上，則將失敗并且返回-1。 ## 32.3.8\. 獲取一個大對象的當前索引位置要獲取一個大對象描述符的當前讀或寫位置，調用 ``` int lo_tell(PGconn *conn, int fd); ``` 如果有錯誤，返回值是-1。當處理可能超過2GB的大對象時，而是使用 ``` pg_int64 lo_tell64(PGconn *conn, int fd); ``` 這個函數有`lo_tell`的相同操作。但是它傳遞大于2GB的結果。注意如果當前讀/寫位置大于2GB，則`lo_tell`失敗。 `lo_tell64`是PostgreSQL 9.3中新的。如果這個函數在一個舊服務器版本上運行，它將失敗并且返回-1。 ## 32.3.9\. 截斷一個大對象截斷一個給定長度的大對象，調用 ``` int lo_truncate(PGcon *conn, int fd, size_t len); ``` 截斷大對象描述符`fd`到長度`len`的大對象， `fd`參數必須通過先前的`lo_open`返回。如果`len`大于當前大對象的長度，大對象延長到空字節('\0')。一旦成功，`lo_truncate`返回零。錯誤時，返回值是-1。與描述符`fd`相聯系的讀/寫位置沒有被改變。盡管`len`參數被聲明為`size_t`，則`lo_truncate` 將拒絕長度值大于`INT_MAX`。當處理可能超過2GB大小的大對象時，而是使用 ``` int lo_truncate64(PGcon *conn, int fd, pg_int64 len); ``` 這個函數和`lo_truncate`有同樣操作，但是它可以接受超過2GB的`len`值。 `lo_truncate`是PostgreSQL 8.3中新的；如果這個函數在一個舊的服務器版本上運行，它將失敗并且返回-1。 `lo_truncate64`是PostgreSQL 9.3中新的；如果這個函數在一個舊的服務器版本上運行，它將失敗并且返回-1。 ## 32.3.10\. 關閉一個大對象描述符一個大對象描述符關閉可以通過調用 ``` int lo_close(PGconn *conn, int fd); ``` `fd`是通過`lo_open`返回的大對象描述符。成功時，`lo_close`返回零。失敗時，返回值是-1。任何在事務結尾時仍然打開的大對象描述符將自動關閉。 ## 32.3.11\. 刪除一個大對象從數據庫中刪除一個大對象，調用 ``` int lo_unlink(PGconn *conn, Oid lobjId); ``` `lobjId`參數聲明要刪除的大對象的OID。成功時返回1，失敗時返回-1。