PostgreSQLシステムでは、ユーザ定義関数の一部としてバックエンド側から、もしくは、アプリケーションの一部としてフロントエンド側からのラージオブジェクトへのアクセスに使用されるインタフェースを提供します。これらは後で説明します。 POSTGRES 4.2に慣れているユーザー向けに、 PostgreSQLはより理路整然としたインタフェースを提供する新しい関数群を持っています。
Note: すべてのラージオブジェクトの操作は必ずSQLのトランザクション内で行う必要があります。この制約は、 PostgreSQL 6.5以前のバージョンでは暗黙の必要条件であり、無視されるため誤動作することになっていましたが、それ以降のバージョンでは厳しく強制されています。
PostgreSQLラージオブジェクトインタフェースは、Unixファイルシステムインタフェースにならって作成され、open(2)、read(2)、 write(2)、lseek(2)などと酷似したインタフェースを持っています。ユーザ関数は、ラージオブジェクトから必要なデータだけを取り出すときにこれらの処理を呼び出します。たとえば、顔写真を格納するbeardという名前のラージオブジェクト型があり、 beard という名前の関数で、mugshotデータについて宣言したとします。beard 関数は写真の下1/3をみて、もしあれば、そこにあるひげの色を測定するものとします。beard 関数では、ラージオブジェクトの値全体をバッファに取り出すことも、全体を確認することも必要ありません。ラージオブジェクトは、動的に読み込まれるC 関数、または、ライブラリとリンクされたデータベースクライアントプログラムのどちらからでもアクセスできます。PostgreSQLは、ラージオブジェクトについて「開く」、「読む」、「書く」、「閉じる」、「シークする」機能を提供しています。
Oid lo_creat(PGconn *conn, int mode)
この処理は、新しいラージオブジェクトを作成します。引数 modeは新しいオブジェクト用の複数の異なる属性を示すビットマスクです。以下で使用する定数シンボルは、libpq/libpq-fs.hで定義されています。アクセスタイプ（読み取り、書き込み、または両方）は、 INV_READビット、INV_WRITEビットの論理和で指定できます。マスクの下位16ビットは、これまではラージオブジェクトが属するストレージマネージャの番号を識別するためにバークレイで使用されていました。現在では、常にゼロにしなければなりません。次のコマンドは、ラージオブジェクトを作成します。
inv_oid = lo_creat(INV_READ|INV_WRITE);
オペレーティングシステム上のファイルをラージオブジェクトとしてインポートするには、以下の関数を呼び出します。
Oid lo_import(PGconn *conn, const char *filename)
引数filenameには、ラージオブジェクトとしてインポートするオペレーティングシステム上のファイルのパス名を指定します。
ラージオブジェクトをオペレーティングシステム上のファイルにエクスポートするには、以下の関数を呼び出します。
int lo_export(PGconn *conn, Oid lobjId, const char *filename)
引数lobjIdには、エクスポートしたいラージオブジェクトのOIDを指定し、引数filenameには、オペレーティングシステム上のファイルのパス名を指定します。
既存のラージオブジェクトを開く場合は、以下の関数を呼び出します。
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で使用するラージオブジェクト記述子を返します。
int lo_write(PGconn *conn, int fd, const char *buf, size_t len)
この処理は、引数len長のバイトを、引数 bufから引数fdが示すラージオブジェクトに書き込みます。引数fdは事前に実行した lo_openの戻り値でなければいけません。実際に書き込まれたバイト数が返されます。エラーが発生した場合は、負の値を返します。
int lo_read(PGconn *conn, int fd, char *buf, size_t len)
この処理は、引数len長のバイトを、引数 fdが示すラージオブジェクトからbuf に読み込みます。引数fdは事前に実行した lo_openの戻り値でなければいけません。実際に読み込まれたバイト数が返されます。エラーが発生した場合は、負の値を返します。
ラージオブジェクトの現在の読み取り、または、書き込みを行う位置を変更するには、以下の関数を呼び出します。
int lo_lseek(PGconn *conn, int fd, int offset, int whence)
この処理は、引数fdで指定されたラージオブジェクトの現在の位置を指すポインタを、引数offsetで指定した新しい位置に変更します。引数whenceに指定可能な値は、SEEK_SET、 SEEK_CUR、SEEK_ENDのいずれかです。
int lo_close(PGconn *conn, int fd)
上記の関数を呼び出すことで、ラージオブジェクトを閉じることができます。ここで、fdはlo_openの戻り値であるラージオブジェクト記述子です。成功すると、lo_closeは0を返します。失敗すると、負の値を返します。
ラージオブジェクトをデータベースから削除するには、以下の関数を呼び出します。
Oid lo_unlink(PGconn *conn, Oid lobjId)
引数lobjIdは削除したいラージオブジェクトのoidを示します。