From 8436f9a0364a6a16dbf7b250597986a97c9e6f09 Mon Sep 17 00:00:00 2001
From: Tatsuo Ishii <ishii@postgresql.org>
Date: Wed, 19 Mar 2008 00:39:33 +0000
Subject: Add libpq new API lo_import_with_oid() which is similar to
 lo_import() except that lob's oid can be specified.

---
 doc/src/sgml/lobj.sgml | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgml
index 0c60988f259..69a21c99cf7 100644
--- a/doc/src/sgml/lobj.sgml
+++ b/doc/src/sgml/lobj.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.46 2007/03/14 00:15:26 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.47 2008/03/19 00:39:33 ishii Exp $ -->
 
  <chapter id="largeObjects">
   <title id="largeObjects-title">Large Objects</title>
@@ -161,6 +161,28 @@ Oid lo_import(PGconn *conn, const char *filename);
      the server; so it must exist in the client file system and be readable
      by the client application.
     </para>
+
+    <para>
+     The function
+<synopsis>
+Oid lo_import_with_oid(PGconn *conn, const char *filename, Oid lobjId);
+</synopsis>
+     <indexterm><primary>lo_import_with_oid</></>
+     also imports a new large object.  The OID to be assigned can be
+     specified by <replaceable class="parameter">lobjId</replaceable>;
+     if so, failure occurs if that OID is already in use for some large
+     object.  If <replaceable class="parameter">lobjId</replaceable>
+     is <symbol>InvalidOid</symbol> (zero) then <function>lo_import_with_oid</> assigns an unused
+     OID (this is the same behavior as <function>lo_import</>).
+     The return value is the OID that was assigned to the new large object,
+     or <symbol>InvalidOid</symbol> (zero) on failure.
+    </para>
+
+    <para>
+     <function>lo_import_with_oid</> is new as of <productname>PostgreSQL</productname>
+     8.4 and uses <function>lo_create</function> internally which is new in 8.1; if this function is run against 8.0 or before, it will
+     fail and return <symbol>InvalidOid</symbol>.
+    </para>
    </sect2>
 
    <sect2>
-- 
cgit v1.2.3