28.3. 客户端接口 #
本节描述 PostgreSQL 客户端接口库为访问大对象所提供的功能。使用这些函数对大对象进行的所有操作必须发生在一个 SQL 事务块内。(从
PostgreSQL 6.5 开始,这一要求被严格强制执行;不过在更早的版本中它一直是隐含的要求,如果忽视就会导致错误行为。)PostgreSQL 的大对象接口是仿照
Unix 文件系统接口设计的,提供了与
open、read、write、lseek 等相对应的操作。
在 libpq 中使用大对象接口的客户端应用应包含头文件
libpq/libpq-fs.h 并与
libpq 库链接。
28.3.1. 创建一个大对象
The function
Oid lo_creat(PGconn *conn, int mode);
创建一个新的大对象。mode是一个位掩码,描述新对象的若干不同属性。这里使用的符号常量定义在头文件
libpq/libpq-fs.h中。访问类型(读、写或两者兼有)由INV_READ和
INV_WRITE两个位按位或在一起控制。掩码的低十六位在伯克利时代历史上曾用来指定大对象应驻留的存储管理器编号。这些位现在应当始终为零。(访问类型实际上也不再起任何作用,但必须设置其中一个或两个标志位,以避免出错。)返回值是分配给新大对象的 OID,失败时为 InvalidOid(零)。
例如:
inv_oid = lo_creat(conn, INV_READ|INV_WRITE);
28.3.2. 导入一个大对象
要把一个操作系统文件导入为大对象,调用
Oid lo_import(PGconn *conn, const char *filename);
filename
指定要作为大对象导入的操作系统文件名。返回值是分配给新大对象的 OID,失败时为 InvalidOid(零)。注意,该文件是由客户端接口库读取的,而不是由服务器读取的;因此它必须存在于客户端文件系统中,并且对客户端应用可读。
28.3.3. 导出一个大对象
要把一个大对象导出到操作系统文件,调用
int lo_export(PGconn *conn, Oid lobjId, const char *filename);
lobjId 参数指定要导出的大对象的 OID,filename 参数指定该文件的操作系统文件名。注意,该文件是由客户端接口库写入的,而不是由服务器写入的。成功时返回 1,失败时返回 -1。
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
中使用。该描述符只在当前事务持续期间有效。失败时返回 -1。
28.3.5. 向大对象写入数据
The function
int lo_write(PGconn *conn, int fd, const char *buf, size_t len);
把
buf 中的 len 个字节写入大对象描述符 fd。fd 参数必须是先前由
lo_open 返回的。返回值是实际写入的字节数。发生错误时,返回值为负。
28.3.6. 从大对象读取数据
The function
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(从对象末尾定位)。返回值是新的位置指针,出错时为 -1。