# 35.3. Client Interfaces
35.3.1. Creating a Large Object
35.3.2. Importing a Large Object
35.3.3. Exporting a Large Object
35.3.4. Opening an Existing Large Object
35.3.5. Writing Data to a Large Object
35.3.6. Reading Data from a Large Object
35.3.7. Seeking in a Large Object
35.3.8. Obtaining the Seek Position of a Large Object
35.3.9. Truncating a Large Object
35.3.10. Closing a Large Object Descriptor
35.3.11. Removing a Large Object
This section describes the facilities that PostgreSQL's libpq client interface library provides for accessing large objects. The PostgreSQL large object interface is modeled after the Unix file-system interface, with analogues ofopen
,read
,write
,lseek
, etc.
All large object manipulation using these functionsmusttake place within an SQL transaction block, since large object file descriptors are only valid for the duration of a transaction.
If an error occurs while executing any one of these functions, the function will return an otherwise-impossible value, typically 0 or -1. A message describing the error is stored in the connection object and can be retrieved withPQerrorMessage
.
Client applications that use these functions should include the header filelibpq/libpq-fs.h
and link with the libpq library.
Client applications cannot use these functions while a libpq connection is in pipeline mode.
# 35.3.1. Creating a Large Object
Oid lo_creat(PGconn *conn, int mode);
creates a new large object. The return value is the OID that was assigned to the new large object, orInvalidOid
(zero) on failure.*mode
*is unused and ignored as of PostgreSQL 8.1; however, for backward compatibility with earlier releases it is best to set it toINV_READ
,INV_WRITE
, orINV_READ
|
INV_WRITE
. (These symbolic constants are defined in the header filelibpq/libpq-fs.h
.)
An example:
inv_oid = lo_creat(conn, INV_READ|INV_WRITE);
Oid lo_create(PGconn *conn, Oid lobjId);
also creates a new large object. The OID to be assigned can be specified by*lobjId
; if so, failure occurs if that OID is already in use for some large object. IflobjId
*isInvalidOid
(零)那么lo_create
分配一个未使用的OID(这与你创造了什么
)。返回值是分配给新大对象的OID,或残疾人
失败时(零)。
lo_create
从PostgreSQL 8.1开始是新的;如果此功能在较旧的服务器版本上运行,它将失败并返回残疾人
.
举个例子:
inv_oid = lo_create(conn, desired_oid);
# 35.3.2.导入大型对象
Oid lo_import(PGconn *conn, const char *filename);
*文件名
*指定要作为大型对象导入的文件的操作系统名称。返回值是分配给新大对象的OID,或残疾人
失败时(零)。请注意,该文件由客户端接口库读取,而不是由服务器读取;因此,它必须存在于客户机文件系统中,并且可以被客户机应用程序读取。
Oid lo_import_with_oid(PGconn *conn, const char *filename, Oid lobjId);
还将导入一个新的大型对象。要分配的OID可以由指定*洛布吉德
; 如果是这样,如果该OID已用于某个大型对象,则会发生故障。如果洛布吉德
*是残疾人
(零)那么lo_导入带有_oid的
分配一个未使用的OID(这与lo_import
). The return value is the OID that was assigned to the new large object, orInvalidOid
(zero) on failure.
lo_import_with_oid
is new as of PostgreSQL 8.4 and useslo_create
internally which is new in 8.1; if this function is run against 8.0 or before, it will fail and returnInvalidOid
.
# 35.3.3. Exporting a Large Object
To export a large object into an operating system file, call
int lo_export(PGconn *conn, Oid lobjId, const char *filename);
The*lobjId
argument specifies the OID of the large object to export and thefilename
*argument specifies the operating system name of the file. Note that the file is written by the client interface library, not by the server. Returns 1 on success, -1 on failure.
# 35.3.4. Opening an Existing Large Object
To open an existing large object for reading or writing, call
int lo_open(PGconn *conn, Oid lobjId, int mode);
The*lobjId
argument specifies the OID of the large object to open. Themode
*bits control whether the object is opened for reading (INV_READ
), writing (INV_WRITE
), or both. (These symbolic constants are defined in the header filelibpq/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 的事务模式选择
命令。
lo_open
如果会失败选择
特权不适用于大对象,或者如果INV_WRITE
被指定并且更新
特权不可用。(在 PostgreSQL 11 之前,这些权限检查是在使用描述符的第一次实际读取或写入调用时执行的。)这些权限检查可以通过罗_兼容_特权run-time parameter.
An example:
inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE);
# 35.3.5. Writing Data to a Large Object
int lo_write(PGconn *conn, int fd, const char *buf, size_t len);
writes*len
bytes frombuf
(which must be of sizelen
) to large object descriptorfd
. Thefd
argument must have been returned by a previouslo_open
. The number of bytes actually written is returned (in the current implementation, this will always equallen
*unless there is an error). In the event of an error, the return value is -1.
Although the*len
*parameter is declared assize_t
, this function will reject length values larger thanINT_MAX
. In practice, it's best to transfer data in chunks of at most a few megabytes anyway.
# 35.3.6. Reading Data from a Large Object
int lo_read(PGconn *conn, int fd, char *buf, size_t len);
reads up to*len
bytes from large object descriptorfd
intobuf
(which must be of sizelen
). Thefd
argument must have been returned by a previouslo_open
. The number of bytes actually read is returned; this will be less thanlen
*if the end of the large object is reached first. In the event of an error, the return value is -1.
Although the*len
*parameter is declared assize_t
, this function will reject length values larger thanINT_MAX
. In practice, it's best to transfer data in chunks of at most a few megabytes anyway.
# 35.3.7. Seeking in a Large Object
To change the current read or write location associated with a large object descriptor, call
int lo_lseek(PGconn *conn, int fd, int offset, int whence);
This function moves the current location pointer for the large object descriptor identified by*fd
to the new location specified byoffset
. The valid values forwhence
*areSEEK_SET
(seek from object start),SEEK_CUR
(seek from current position), andSEEK_END
(seek from object end). The return value is the new location pointer, or -1 on error.
When dealing with large objects that might exceed 2GB in size, instead use
pg_int64 lo_lseek64(PGconn *conn, int fd, pg_int64 offset, int whence);
This function has the same behavior aslo_lseek
, but it can accept an*offset
*larger than 2GB and/or deliver a result larger than 2GB. Note thatlo_lseek
will fail if the new location pointer would be greater than 2GB.
lo_lseek64
is new as of PostgreSQL 9.3. If this function is run against an older server version, it will fail and return -1.
# 35.3.8. Obtaining the Seek Position of a Large Object
To obtain the current read or write location of a large object descriptor, call
int lo_tell(PGconn *conn, int fd);
If there is an error, the return value is -1.
When dealing with large objects that might exceed 2GB in size, instead use
pg_int64 lo_tell64(PGconn *conn, int fd);
This function has the same behavior aslo_tell
, but it can deliver a result larger than 2GB. Note thatlo_tell
will fail if the current read/write location is greater than 2GB.
lo_tell64
is new as of PostgreSQL 9.3. If this function is run against an older server version, it will fail and return -1.
# 35.3.9. Truncating a Large Object
To truncate a large object to a given length, call
int lo_truncate(PGconn *conn, int fd, size_t len);
This function truncates the large object descriptor*fd
to lengthlen
. Thefd
argument must have been returned by a previouslo_open
. Iflen
*is greater than the large object's current length, the large object is extended to the specified length with null bytes ('\0'). On success,lo_truncate
returns zero. On error, the return value is -1.
The read/write location associated with the descriptor*fd
*is not changed.
Although the*len
*parameter is declared assize_t
,lo_truncate
will reject length values larger thanINT_MAX
.
When dealing with large objects that might exceed 2GB in size, instead use
int lo_truncate64(PGconn *conn, int fd, pg_int64 len);
This function has the same behavior aslo_truncate
, but it can accept a*len
*value exceeding 2GB.
lo_truncate
is new as of PostgreSQL 8.3; if this function is run against an older server version, it will fail and return -1.
lo_truncate64
is new as of PostgreSQL 9.3; if this function is run against an older server version, it will fail and return -1.
# 35.3.10. Closing a Large Object Descriptor
A large object descriptor can be closed by calling
int lo_close(PGconn *conn, int fd);
where*fd
*is a large object descriptor returned bylo_open
. On success,lo_close
returns zero. On error, the return value is -1.
Any large object descriptors that remain open at the end of a transaction will be closed automatically.
# 35.3.11. Removing a Large Object
To remove a large object from the database, call
int lo_unlink(PGconn *conn, Oid lobjId);
The*lobjId
*argument specifies the OID of the large object to remove. Returns 1 if successful, -1 on failure.