本节描述 PostgreSQL 客户端接口库提供来访问大对象的设施。 所有使用这些函数进行的大对象操作都必须在一个SQL事务里实现。 (这个要求是自 PostgreSQL 6.5 以来的一个严格的要求,虽然在以前的版本里就隐含这样的要求,如果忽略这一点会导致错误的表现。) PostgreSQL大对象接口是对 Unix 文件系统的模仿,有仿真的 open,read, write, lseek,等.
使用 libpq 里面大对象接口的的客户端应用应该包含头文件 libpq/libpq-fs.h 并且和 libpq 库链接。
函数
Oid lo_creat(PGconn *conn, int mode);
创建一个新的大对象. mode是一个位掩码, 描述新对象的不同属性。 这里使用的符号常量在 libpq/libpq-fs.h 列出。 访问类型(读,写或者两者)是对位 INV_READ 和 INV_WRITE进行或操作构成的。 掩码的低十六位是大对象要存放于内的存储管理器号。 对于除 Berkeley (伯克利)以外的节点,这些位都应总是零。 (访问类型现在实际上也不作任何事情,但是其中一个或者两个位都需要置上,以避免错误。) 返回值是赋予新大对象的 OID,或者是失败的时候是 InvalidOid(零)。
例子:
inv_oid = lo_creat(conn, INV_READ|INV_WRITE);
要把一个操作系统文件输入成为大对象,调用
Oid lo_import(PGconn *conn, const char *filename);
filename 参数指明要被输入成为大对象的操作系统文件路径名。返回值是赋予新大对象的 OID。 如果失败则返回 InvalidOid(零)。请注意这个文件是由客户端接口库读取的, 而不是服务器端;因此它必须存在于客户端文件系统上并且可以被客户应用读取。
要把一个大对象输出为操作系统文件,调用
int lo_export(PGconn *conn, Oid lobjId, const char *filename);
lobjId参数指明要输出的大对象 OID,filename 参数指明操作系统文件的路径名。请注意这个文件是由客户端接口库写入的, 而不是服务器端。成功时返回 1,失败时返回 -1。
要打开一个现存的大对象读写,调用
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。
函数
int lo_write(PGconn *conn, int fd, const char *buf, size_t len);
从buf中向大对象描述符fd中写len字节. 参数fd必须是前面一个 lo_open 调用的返回。 返回实际写的字节数.出错时返回负数.
函数
int lo_read(PGconn *conn, int fd, char *buf, size_t len);
从大对象描述符 fd 中读取len字节数据到buf中。 fd参数必须是前面的一个 lo_open调用的返回。 返回实际读取的字节数。出错时,返回一个负数。
要改变与一个大对象描述符相关的读写位置,调用
int lo_lseek(PGconn *conn, int fd, int offset, int whence);
这个过程把当前fd代表的大对象描述符位置指针移动到 offset指明的新的位置。 参数whence的合法的取值是 SEEK_SET(从对象开头开始找),SEEK_CUR(从当前位置开始找),和SEEK_END (从对象结尾开始找)。返回值是新位置指针,如果出错为 -1。
可以通过调用
int lo_close(PGconn *conn, int fd);
关闭一个大对象描述符,这里fd是 lo_open返回的大对象的描述符.成功时, lo_close 返回零.错误时,返回值是负数.
任何在事务结尾时仍然打开的大对象描述符将在事务结束时自动关闭。