Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps
 (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1nEeny-0006cf-Po
	for pgsql-docs@arkaria.postgresql.org; Mon, 31 Jan 2022 22:05:46 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1nEenx-00062h-CU
	for pgsql-docs@arkaria.postgresql.org; Mon, 31 Jan 2022 22:05:45 +0000
Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29])
	by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1nEenx-00062Y-4i
	for pgsql-docs@lists.postgresql.org; Mon, 31 Jan 2022 22:05:45 +0000
Received: from sss.pgh.pa.us ([66.207.139.130])
	by magus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1nEenq-0000sc-US
	for pgsql-docs@lists.postgresql.org; Mon, 31 Jan 2022 22:05:44 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.15.2/8.15.2) with ESMTP id 20VM5ZTJ840939;
	Mon, 31 Jan 2022 17:05:35 -0500
From: Tom Lane <tgl@sss.pgh.pa.us>
To: Daniel Gustafsson <daniel@yesql.se>
cc: Magnus Hagander <magnus@hagander.net>, supersuper1231@outlook.com,
        pgsql-docs@lists.postgresql.org
Subject: Re: documentation typo
In-reply-to: <302C1B62-E6D8-4DD9-BF61-B5FADCF8081C@yesql.se>
References: <164353261519.713.8748040527537500758@wrigleys.postgresql.org>
 <CABUevEx7VxvcgKGyveqyDsrK8ZCpR78OCMK+9djJW2SUpUe=5Q@mail.gmail.com>
 <217854.1643557968@sss.pgh.pa.us>
 <302C1B62-E6D8-4DD9-BF61-B5FADCF8081C@yesql.se>
Comments: In-reply-to Daniel Gustafsson <daniel@yesql.se>
	message dated "Mon, 31 Jan 2022 11:53:43 +0100"
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0"
Content-ID: <840914.1643666709.0@sss.pgh.pa.us>
Date: Mon, 31 Jan 2022 17:05:35 -0500
Message-ID: <840938.1643666735@sss.pgh.pa.us>
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Archived-At: 
 <https://www.postgresql.org/message-id/840938.1643666735%40sss.pgh.pa.us>
Precedence: bulk

------- =_aaaaaaaaaa0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <840914.1643666709.1@sss.pgh.pa.us>
Content-Transfer-Encoding: quoted-printable

Daniel Gustafsson <daniel@yesql.se> writes:
>> On 30 Jan 2022, at 16:52, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> I could get behind documenting the more modern
>> one first, though.

> +1

Proposed patch attached.

>> I wonder if it's time to remove the references to PG 8.1?

> I think it's time to remove references to 8.0 and 8.1 to de-clutter the =
page,
> 8.3 or 8.4 seems like a better lower limit to keep.

It's hard to explain why lo_creat is there at all without mentioning
8.1, so I ended up with the below, which basically says that lo_creat
is only useful for talking to pre-8.1 servers.  Comments?

			regards, tom lane


------- =_aaaaaaaaaa0
Content-Type: text/x-diff; name="rearrange-lo-create-docs.patch";
	charset="us-ascii"
Content-ID: <840914.1643666709.2@sss.pgh.pa.us>
Content-Description: rearrange-lo-create-docs.patch
Content-Transfer-Encoding: quoted-printable

diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgml
index 57bb57083a..b767ba1d05 100644
--- a/doc/src/sgml/lobj.sgml
+++ b/doc/src/sgml/lobj.sgml
@@ -138,57 +138,59 @@
     <title>Creating a Large Object</title>
 =

     <para>
-     <indexterm><primary>lo_creat</primary></indexterm>
+     <indexterm><primary>lo_create</primary></indexterm>
      The function
 <synopsis>
-Oid lo_creat(PGconn *conn, int mode);
+Oid lo_create(PGconn *conn, Oid lobjId);
 </synopsis>
-     creates a new large object.
+     creates a new large object.  The OID to be assigned can be
+     specified by <replaceable class=3D"parameter">lobjId</replaceable>;
+     if so, failure occurs if that OID is already in use for some large
+     object.  If <replaceable class=3D"parameter">lobjId</replaceable>
+     is <symbol>InvalidOid</symbol> (zero) then <function>lo_create</func=
tion>
+     assigns an unused OID.
      The return value is the OID that was assigned to the new large objec=
t,
      or <symbol>InvalidOid</symbol> (zero) on failure.
-
-     <replaceable class=3D"parameter">mode</replaceable> is unused and
-     ignored as of <productname>PostgreSQL</productname> 8.1; however, fo=
r
-     backward compatibility with earlier releases it is best to
-     set it to <symbol>INV_READ</symbol>, <symbol>INV_WRITE</symbol>,
-     or <symbol>INV_READ</symbol> <literal>|</literal> <symbol>INV_WRITE<=
/symbol>.
-     (These symbolic constants are defined
-     in the header file <filename>libpq/libpq-fs.h</filename>.)
     </para>
 =

     <para>
      An example:
 <programlisting>
-inv_oid =3D lo_creat(conn, INV_READ|INV_WRITE);
+inv_oid =3D lo_create(conn, desired_oid);
 </programlisting>
     </para>
 =

     <para>
-     <indexterm><primary>lo_create</primary></indexterm>
-     The function
+     <indexterm><primary>lo_creat</primary></indexterm>
+     The older function
 <synopsis>
-Oid lo_create(PGconn *conn, Oid lobjId);
+Oid lo_creat(PGconn *conn, int mode);
 </synopsis>
-     also creates a new large object.  The OID to be assigned can be
-     specified by <replaceable class=3D"parameter">lobjId</replaceable>;
-     if so, failure occurs if that OID is already in use for some large
-     object.  If <replaceable class=3D"parameter">lobjId</replaceable>
-     is <symbol>InvalidOid</symbol> (zero) then <function>lo_create</func=
tion> assigns an unused
-     OID (this is the same behavior as <function>lo_creat</function>).
+     also creates a new large object, always assigning an unused OID.
      The return value is the OID that was assigned to the new large objec=
t,
      or <symbol>InvalidOid</symbol> (zero) on failure.
     </para>
 =

     <para>
-     <function>lo_create</function> is new as of <productname>PostgreSQL<=
/productname>
-     8.1; if this function is run against an older server version, it wil=
l
-     fail and return <symbol>InvalidOid</symbol>.
+     In <productname>PostgreSQL</productname> releases 8.1 and later,
+     the <replaceable class=3D"parameter">mode</replaceable> is ignored,
+     so that <function>lo_creat</function> is exactly equivalent to
+     <function>lo_create</function> with a zero second argument.
+     However, there is little reason to use <function>lo_creat</function>
+     unless you need to work with servers older than 8.1.
+     To work with such an old server, you must
+     use <function>lo_creat</function> not <function>lo_create</function>=
,
+     and you must set <replaceable class=3D"parameter">mode</replaceable>=
 to
+     one of <symbol>INV_READ</symbol>, <symbol>INV_WRITE</symbol>,
+     or <symbol>INV_READ</symbol> <literal>|</literal> <symbol>INV_WRITE<=
/symbol>.
+     (These symbolic constants are defined
+     in the header file <filename>libpq/libpq-fs.h</filename>.)
     </para>
 =

     <para>
      An example:
 <programlisting>
-inv_oid =3D lo_create(conn, desired_oid);
+inv_oid =3D lo_creat(conn, INV_READ|INV_WRITE);
 </programlisting>
     </para>
    </sect2>

------- =_aaaaaaaaaa0--