32.3. 客户端接口

本节描述PostgreSQL的libpq客户端接口库提供来访问大对象的设施。 PostgreSQL大对象接口是对Unix文件系统的模仿, 有仿真的openreadwritelseek等。

使用这些函数的所有大对象操作必须在一个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_readlo_writelo_lseeklo_lseek64lo_telllo_tell64lo_truncatelo_truncate64lo_close。 这个描述符只是在当前事务中有效。 失败的时候,返回-1。

服务器目前并不区分INV_WRITEINV_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。