28.3. クライアントインタフェース

28.3.1. ラージオブジェクトの作成

Oid lo_creat(PGconn *conn, int mode);

この関数はラージオブジェクトを新規に作成します。 modeは、新規オブジェクトの多くの各種属性を記述するビットマスクです。 ここで示す定数シンボルはlibpq/libpq-fs.hヘッダファイルで定義されています。 アクセス種類(読みとり、書き込み、もしくはその両方)は、INV_READビットとINV_WRITEビットの論理和を取ることで制御されます。 このマスクの下位16ビットは、過去バークレイにおいて、ラージオブジェクトを格納する、格納管理番号を識別するために使用されていました。 現在、これらのビットは常にゼロでなければなりません。 戻り値は、新規ラージオブジェクトに割り当てられたOIDです。

以下に例を示します。

inv_oid = lo_creat(INV_READ|INV_WRITE);

28.3.2. ラージオブジェクトのインポート

オペレーティングシステム上のファイルをラージオブジェクトとしてインポートするには、以下の関数を呼び出します。

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

filenameには、ラージオブジェクトとしてインポートするオペレーティングシステム上のファイルのパス名を指定します。 戻り値は、新規ラージオブジェクトに割り当てられたOIDです。

28.3.3. ラージオブジェクトのエクスポート

ラージオブジェクトをオペレーティングシステム上のファイルにエクスポートするには、以下の関数を呼び出します。

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

lobjIdには、エクスポートさせるラージオブジェクトのOIDを指定し、filenameには、オペレーティングシステム上のファイルのパス名を指定します。

28.3.4. 既存のラージオブジェクトのオープン

既存のラージオブジェクトを開く場合は、以下の関数を呼び出します。

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で使用するラージオブジェクト記述子を返します。 この記述子は現在のトランザクション期間のみで有効です。

28.3.5. ラージオブジェクトへのデータの書き込み

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

この関数は、len 長のバイトを、buf からfd が示すラージオブジェクトに書き込みます。 fd引数は事前に実行したlo_openの戻り値でなければいけません。 実際に書き込まれたバイト数が返されます。 エラーが発生した場合は、負の値を返します。

28.3.6. ラージオブジェクトからのデータの読み込み

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

この関数は、len 長のバイトを、fd が示すラージオブジェクトから buf に読み込みます。 fd引数は事前に実行したlo_openの戻り値でなければいけません。 実際に読み込まれたバイト数が返されます。 エラーが発生した場合は、負の値を返します。

28.3.7. ラージオブジェクトのシーク

ラージオブジェクトの現在の読み取り、または、書き込みを行う位置を変更するには、以下の関数を呼び出します。

int lo_lseek(PGconn *conn, int fd, int offset, int whence);

この関数はfd で指定されたラージオブジェクトの現在の位置を指すポインタを、offset で指定した新しい位置に変更します。 whenceに指定可能な値は、SEEK_SET(オブジェクトの先頭位置からシーク)、SEEK_CUR(現在位置からシーク)、SEEK_END(オブジェクトの末尾位置からシーク)のいずれかです。 戻り値は新しい位置ポインタです。

28.3.8. ラージオブジェクトのシーク位置の入手

ラージオブジェクトの現在の読みとり、書き込み位置を入手するには、以下の関数を呼び出します。

int lo_tell(PGconn *conn, int fd);

エラーが発生した場合は負の値が返されます。

28.3.9. ラージオブジェクト記述子を閉じる

以下を呼び出すことでラージオブジェクトを閉ざすことができます。

int lo_close(PGconn *conn, int fd);

ここで、fdはlo_openの戻り値であるラージオブジェクト記述子です。 成功すると、lo_closeは0を返します。 失敗すると、負の値を返します。

開いたままのラージオブジェクト記述子はすべてトランザクションの終了時に自動的に閉ざされます。

28.3.10. ラージオブジェクトの削除

データベースからラージオブジェクトを削除するには、以下の関数を呼び出します。

int lo_unlink(PGconn *conn, Oid lobjId);

lobjId引数は削除するラージオブジェクトのOIDを指定します。 エラーが発生した場合は、負の値を返します。