Doc: modernize documentation for lo_create()/lo_creat().

At this point lo_creat() is a legacy function with little if any
real use-case, so describing it first doesn't make much sense.
Describe lo_create() first, and then explain lo_creat() as a
backwards-compatibility alternative.

Discussion: https://postgr.es/m/164353261519.713.8748040527537500758@wrigleys.postgresql.org

diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgml
index 57bb57083a51e220cfcefff04897e7ef13af2e13..b767ba1d05155f1b6bb4f9262c310f01c4ddcac0 100644 (file)
--- a/doc/src/sgml/lobj.sgml
+++ b/doc/src/sgml/lobj.sgml
@@ -138,57 +138,59 @@
     Creating a Large Object
 
     
-     lo_creat
+     lo_create
      The function
 
-Oid lo_creat(PGconn *conn, int mode);
+Oid lo_create(PGconn *conn, Oid lobjId);
 
-     creates a new large object.
+     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.
      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);
+inv_oid = lo_create(conn, desired_oid);
 
     
 
     
-     lo_create
-     The function
+     lo_creat
+     The older function
 
-Oid lo_create(PGconn *conn, Oid lobjId);
+Oid lo_creat(PGconn *conn, int mode);
 
-     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).
+     also creates a new large object, always assigning an unused OID.
      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.
+     In PostgreSQL releases 8.1 and later,
+     the mode is ignored,
+     so that lo_creat is exactly equivalent to
+     lo_create with a zero second argument.
+     However, there is little reason to use lo_creat
+     unless you need to work with servers older than 8.1.
+     To work with such an old server, you must
+     use lo_creat not lo_create,
+     and you must set mode to
+     one of 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_create(conn, desired_oid);
+inv_oid = lo_creat(conn, INV_READ|INV_WRITE);