Client Interfaces

PostgreSQL 9.1.24 Documentation
Prev | Up | Chapter 32. Large Objects | Next

# 32.3. Client Interfaces

This section describes the facilities that PostgreSQL client interface libraries provide for accessing large objects. All large object manipulation using these functions must take place within an SQL transaction block. The PostgreSQL large object interface is modeled after the Unix file-system interface, with analogues of `open`, `read`, `write`, `lseek`, etc.

Client applications which use the large object interface in libpq should include the header file `libpq/libpq-fs.h` and link with the libpq library.

## 32.3.1. Creating a Large Object

The function

    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, or `InvalidOid` (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 to `INV_READ`, `INV_WRITE`, or `INV_READ` `|` `INV_WRITE`. (These symbolic constants are defined in the header file `libpq/libpq-fs.h`.)

An example:

    inv_oid = lo_creat(conn, INV_READ|INV_WRITE);

The function

    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. If `lobjId` is `InvalidOid` (zero) then `lo_create` assigns an unused OID (this is the same behavior as `lo_creat`). The return value is the OID that was assigned to the new large object, or `InvalidOid` (zero) on failure.

`lo_create` is new as of PostgreSQL 8.1; if this function is run against an older server version, it will fail and return `InvalidOid`.

An example:

    inv_oid = lo_create(conn, desired_oid);

## 32.3.2. Importing a Large Object

To import an operating system file as a large object, call

    Oid lo_import(PGconn *conn, const char *filename);

`filename` specifies the operating system name of the file to be imported as a large object. The return value is the OID that was assigned to the new large object, or `InvalidOid` (zero) on failure. Note that the file is read by the client interface library, not by the server; so it must exist in the client file system and be readable by the client application.

The function

    Oid lo_import_with_oid(PGconn *conn, const char *filename, Oid lobjId);

also imports 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. If `lobjId` is `InvalidOid` (zero) then `lo_import_with_oid` assigns an unused OID (this is the same behavior as `lo_import`). The return value is the OID that was assigned to the new large object, or `InvalidOid` (zero) on failure.

`lo_import_with_oid` is new as of PostgreSQL 8.4 and uses `lo_create` internally which is new in 8.1; if this function is run against 8.0 or before, it will fail and return `InvalidOid`.

## 32.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 the `filename` 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.

## 32.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. The `mode` bits control whether the object is opened for reading (`INV_READ`), writing (`INV_WRITE`), or both. (These symbolic constants are defined in the header file `libpq/libpq-fs.h`.) A large object cannot be opened before it is created. `lo_open` returns a (non-negative) large object descriptor for later use in `lo_read`, `lo_write`, `lo_lseek`, `lo_tell`, and `lo_close`. The descriptor is only valid for the duration of the current transaction. On failure, -1 is returned.

The server currently does not distinguish between modes `INV_WRITE` and `INV_READ` `|` `INV_WRITE`: you are allowed to read from the descriptor in either case. However there is a significant difference between these modes and `INV_READ` alone: with `INV_READ` you cannot write on the descriptor, and the data read from it will reflect the contents of the large object at the time of the transaction snapshot that was active when `lo_open` was executed, regardless of later writes by this or other transactions. Reading from a descriptor opened with `INV_WRITE` returns data that reflects all writes of other committed transactions as well as writes of the current transaction. This is similar to the behavior of `REPEATABLE READ` versus `READ COMMITTED` transaction modes for ordinary SQL `SELECT` commands.

An example:

    inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE);

## 32.3.5. Writing Data to a Large Object

The function

    int lo_write(PGconn *conn, int fd, const char *buf, size_t len);

writes `len` bytes from `buf` to large object descriptor `fd`. The `fd` argument must have been returned by a previous `lo_open`. The number of bytes actually written is returned. In the event of an error, the return value is negative.

## 32.3.6. Reading Data from a Large Object

The function

    int lo_read(PGconn *conn, int fd, char *buf, size_t len);

reads `len` bytes from large object descriptor `fd` into `buf`. The `fd` argument must have been returned by a previous `lo_open`. The number of bytes actually read is returned. In the event of an error, the return value is negative.

## 32.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 by `offset`. The valid values for `whence` are `SEEK_SET` (seek from object start), `SEEK_CUR` (seek from current position), and `SEEK_END` (seek from object end). The return value is the new location pointer, or -1 on error.

## 32.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 negative.

## 32.3.9. Truncating a Large Object

To truncate a large object to a given length, call

    int lo_truncate(PGcon *conn, int fd, size_t len);

truncates the large object descriptor `fd` to length `len`. The `fd` argument must have been returned by a previous `lo_open`. If `len` is greater than the current large object length, the large object is extended with null bytes ('\0').

The file offset is not changed.

On success `lo_truncate` returns zero. On error, the return value is negative.

`lo_truncate` is new as of PostgreSQL 8.3; if this function is run against an older server version, it will fail and return a negative value.

## 32.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 by `lo_open`. On success, `lo_close` returns zero. On error, the return value is negative.

Any large object descriptors that remain open at the end of a transaction will be closed automatically.

## 32.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.

Prev | Home | Next
Implementation Features | Up | Server-side Functions