From: Tom Lane <tgl@sss.pgh.pa.us>
To: Daniel Gustafsson <daniel@yesql.se>
Cc: Magnus Hagander <magnus@hagander.net>
Cc: supersuper1231@outlook.com
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: documentation typo
Date: Mon, 31 Jan 2022 17:05:35 -0500
Message-ID: <840938.1643666735@sss.pgh.pa.us> (raw)
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>
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
Attachments:
[text/x-diff] rearrange-lo-create-docs.patch (3.8K, ../840938.1643666735@sss.pgh.pa.us/2-rearrange-lo-create-docs.patch)
download | inline diff:diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgmlindex 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="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_create</function>+ assigns an unused OID.
The return value is the OID that was assigned to the new large object,
or <symbol>InvalidOid</symbol> (zero) on failure.
-- <replaceable class="parameter">mode</replaceable> is unused and- ignored as of <productname>PostgreSQL</productname> 8.1; however, for- 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 = lo_creat(conn, INV_READ|INV_WRITE);+inv_oid = 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="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_create</function> 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 object,
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 will- fail and return <symbol>InvalidOid</symbol>.+ In <productname>PostgreSQL</productname> releases 8.1 and later,+ the <replaceable class="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="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 = lo_create(conn, desired_oid);+inv_oid = lo_creat(conn, INV_READ|INV_WRITE);
</programlisting>
</para>
</sect2>
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: tgl@sss.pgh.pa.us, daniel@yesql.se, magnus@hagander.net, supersuper1231@outlook.com, pgsql-docs@lists.postgresql.org
Subject: Re: documentation typo
In-Reply-To: <840938.1643666735@sss.pgh.pa.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox