客户端接口
客户端接口¶
本节描述SeaboxSQL的libpq客户端接口为访问大对象所提供的功能。SeaboxSQL的大对象接口按照Unix文件系统的接口建模，也有相似的open、read、write、lseek等。
所有使用这些函数对大对象的操作都必须发生在一个SQL事务块中，因为大对象文件描述符只在事务期间有效。
在执行任何一个这种函数期间如果发生一个错误，该函数将会返回一个其他的不可能值，典型的是0或-1。一个关于该错误的消息亦会被保存在连接对象中，可以通过PQerrorMessage检索到。
使用这些函数的客户端应用应该包括头文件libpq/libpq-fs.h并链接libpq库。
创建一个大对象¶
函数
Oid lo_creat(PGconn *conn, int mode);
创建一个新的大对象。其返回值是分配给这个新大对象的OID或者InvalidOid（0）表示失败。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（0），则lo_create会分配一个未使用的OID（这时和lo_creat的行为相同）。返回值是分配给新大对象的OID或InvalidOid（0）表示发生错误。
一个例子：
inv_oid = lo_create(conn, desired_oid);
导入一个大对象¶
要将一个操作系统文件导入成一个大对象，调用：
Oid lo_import(PGconn *conn, const char *filename);
filename指定了要导入为大对象的操作系统文件名。返回值是分配给新大对象的OID或InvalidOid（0）表示发生错误。注意该文件是被客户端接口库而不是服务所读取，因此它必须存在于客户端文件系统中并且对于客户端应用是可读的。
函数
Oid lo_import_with_oid(PGconn *conn, const char *filename, Oid lobjId);
也可以导入一个新大对象。分配给新大对象的OID可以用lobjId指定，如果这样做，该OID已经被某个大对象使用时会产生错误。如果lobjId是InvalidOid（0），则lo_import_with_oid会分配一个未使用的OID（这和lo_import的行为相同）。返回值是分配给新大对象的OID或InvalidOid（0）表示发生错误。
导出一个大对象¶
要把一个大对象导出到一个操作系统文件，调用：
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）或者读写（这些符号常量定义在头文件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事务模式之间的区别相似。
如果大对象的SELECT特权不可用，或者如果在指定了INV_WRITE时UPDATE特权不可用，则lo_open将会失败。这些特权检查可以用lo_compat_privileges运行时参数禁用。
一个例子：
inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE);
向一个大对象写入数据¶
函数
int lo_write(PGconn *conn, int fd, const char *buf, size_t len);
从 buf （大小必须是 len ）中写出 len 字节到大对象描述符 fd。参数 fd 必须是已经由前面的lo_open返回的大对象描述符。函数将返回实际写入的字节数（在当前的实现中，除非出错，返回的字节数总是等于 len ）。在出错时，返回值为-1。
尽管参数 len 被声明为类型size_t，该函数会拒绝超过INT_MAX的长度值。在实际中，被传送的数据最好是每块最多数兆字节。
从一个大对象读取数据¶
函数
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的长度值。在实际中，被传送的数据最好是每块最多数兆字节。
在一个大对象中查找¶
要改变一个大对象描述符的当前读或写位置，调用：
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相同，但是它能接受一个超过2GB的offset并/或传送一个超过2GB的结果。注意如果新位置的指针超过2GB，lo_lseek会失败。
获取一个大对象的查找位置¶
要得到一个大对象描述符的当前读或写位置，调用：
int lo_tell(PGconn *conn, int fd);
如果出现错误，返回值是-1。
在处理可能超过2GB大小的大对象时，换用：
pg_int64 lo_tell64(PGconn *conn, int fd);
该函数和lo_tell的行为相同，但是它能传递超过2GB的结果。注意如果当前读/写位置超过2GB，lo_tell将会失败。
截断一个大对象¶
要将一个大对象截断成一个给定长度，调用：
int lo_truncate(PGcon *conn, int fd, size_t len);
该函数将大对象描述符 fd 截断为长度 len。参数 fd 必须是已经由前面的lo_open返回的大对象描述符。如果 len 超过了大对象的当前长度，大对象将会被使用空字节（'\0'）扩展到指定长度。成功时lo_truncate返回0，失败时返回值为-1。
描述 fd 的读/写位置不变。
尽管参数 len 被声明为类型size_t，lo_truncate会拒绝超过INT_MAX的长度值。
在处理可能超过2GB大小的大对象时，换用：
int lo_truncate64(PGcon *conn, int fd, pg_int64 len);
该函数和lo_truncate的行为相同，但它能够接受超过2GB的 len 值。
关闭一个大对象描述符¶
要关闭一个大对象描述符，调用：
int lo_close(PGconn *conn, int fd);
其中 fd 是由lo_open返回的大对象描述符。成功时，lo_close返回0，失败时返回-1。
在事务末尾仍然保持打开的任何大对象描述符都会自动被关闭。
移除一个大对象¶
要从数据库中移除一个大对象，调用：
int lo_unlink(PGconn *conn, Oid lobjId);
lobjId 参数指定要移除的大对象的OID。成功时返回1，失败时返回-1。