28.3. 客户端接口 #
本节描述 PostgreSQL 客户端接口库为访问大对象所提供的功能。使用这些函数对大对象进行的所有操作必须发生在一个 SQL 事务块内。(从
PostgreSQL 6.5 开始,这一要求被严格强制执行;不过在更早的版本中它一直是隐含的要求,如果忽视就会导致错误行为。)PostgreSQL 的大对象接口是仿照
Unix 文件系统接口设计的,提供了与
open、read、write、lseek 等相对应的操作。
在 libpq 中使用大对象接口的客户端应用应包含头文件
libpq/libpq-fs.h 并与
libpq 库链接。
28.3.1. 创建一个大对象
函数
Oid lo_creat(PGconn *conn, int mode);
创建一个新的大对象。mode 是一个位掩码,描述新大对象的若干不同属性。这里列出的符号常量定义在头文件
libpq/libpq-fs.h 中。访问类型(读、写或读写)由把
INV_READ 和
INV_WRITE 位"或"在一起来控制。历史上,掩码的低十六位在伯克利被用来指定大对象应驻留的存储管理器编号。现在这些位应当始终为零。返回值就是分配给新大对象的
OID。
例如:
inv_oid = lo_creat(INV_READ|INV_WRITE);
28.3.2. 导入一个大对象
要把一个操作系统文件导入为大对象,调用
Oid lo_import(PGconn *conn, const char *filename);
28.3.3. 导出一个大对象
要把一个大对象导出到操作系统文件,调用
int lo_export(PGconn *conn, Oid lobjId, const char *filename);
28.3.4. 打开一个现有的大对象
要打开一个现有的大对象,调用
int lo_open(PGconn *conn, Oid lobjId, int mode);
lobjId 参数指定要打开的大对象的
OID。mode 位控制对象是以读(INV_READ)、写(INV_WRITE)还是读写方式打开。大对象在创建之前无法打开。lo_open 返回一个大对象描述符,供稍后在
lo_read、lo_write、lo_lseek、lo_tell 和
lo_close 中使用。该描述符只在当前事务期间有效。
28.3.5. 向大对象写入数据
函数
int lo_write(PGconn *conn, int fd, const char *buf, size_t len);
把
len 字节从 buf
写入大对象 fd。fd
参数必须是先前某个 lo_open
返回的。返回值是实际写入的字节数。发生错误时,返回值为负。
28.3.6. 从大对象读取数据
函数
int lo_read(PGconn *conn, int fd, char *buf, size_t len);
从大对象
fd 中读取
len 字节到 buf。fd
参数必须是先前某个 lo_open
返回的。返回值是实际读取的字节数。发生错误时,返回值为负。
28.3.7. 在大对象上定位
要更改大对象上当前的读或写位置,调用
int lo_lseek(PGconn *conn, int fd, int offset, int whence);
此函数把
fd 所描述大对象的当前位置指针移动到
offset 指定的新位置。whence
的有效值是 SEEK_SET(从对象开头定位)、SEEK_CUR(从当前位置定位)和
SEEK_END(从对象末尾定位)。返回值是新的位置指针。