From a2fb7b8a1f1352b26cd5f99ebed5fea6fd64f54c Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Mon, 13 Jun 2005 02:26:53 +0000 Subject: Adjust lo_open() so that specifying INV_READ without INV_WRITE creates a descriptor that uses the current transaction snapshot, rather than SnapshotNow as it did before (and still does if INV_WRITE is set). This means pg_dump will now dump a consistent snapshot of large object contents, as it never could do before. Also, add a lo_create() function that is similar to lo_creat() but allows the desired OID of the large object to be specified. This will simplify pg_restore considerably (but I'll fix that in a separate commit). --- doc/src/sgml/lobj.sgml | 93 +++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 74 insertions(+), 19 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgml index 82ca839efb2..98516082c97 100644 --- a/doc/src/sgml/lobj.sgml +++ b/doc/src/sgml/lobj.sgml @@ -1,5 +1,5 @@ @@ -115,26 +115,52 @@ $PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.36 2005/01/10 00:04:38 tgl Exp $ Oid lo_creat(PGconn *conn, int mode); lo_creat - creates a new large object. - mode is a bit mask - describing several different attributes of the new - object. The symbolic constants used here are defined - in the header file libpq/libpq-fs.h. - The access type (read, write, or both) is controlled by - or'ing together the bits INV_READ and - INV_WRITE. The low-order sixteen bits of the mask have - historically been used at Berkeley to designate the storage manager number on which the large object - should reside. These bits should always be zero now. (The access type - does not actually do anything anymore either, but one or both flag bits - must be set to avoid an error.) + 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 + backwards 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); + + lo_create + 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); @@ -186,11 +212,13 @@ int lo_export(PGconn *conn, Oid lobjId, const char *filename); int lo_open(PGconn *conn, Oid lobjId, int mode); lo_open - 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. - A large object cannot be opened before it is created. + 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, @@ -198,7 +226,31 @@ int lo_open(PGconn *conn, Oid lobjId, int mode); 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 SERIALIZABLE versus READ COMMITTED transaction + modes for ordinary SQL SELECT commands. + + + + An example: + +inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE); + + @@ -317,6 +369,7 @@ int lo_unlink(PGconn *conn, Oid lobjId); equivalent server-side functions. The ones that are actually useful to call via SQL commands are lo_creatlo_creat, + lo_createlo_create, lo_unlinklo_unlink, lo_importlo_import, and lo_exportlo_export. @@ -330,6 +383,8 @@ CREATE TABLE image ( SELECT lo_creat(-1); -- returns OID of new, empty large object +SELECT lo_create(43213); -- attempts to create large object with OID 43213 + SELECT lo_unlink(173454); -- deletes large object with OID 173454 INSERT INTO image (name, raster) -- cgit v1.2.3