pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feeddocumentation typo
6+ messages / 4 participants
[nested] [flat]
* documentation typo
@ 2022-01-30 08:50 PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 6+ messages in thread
From: PG Doc comments form @ 2022-01-30 08:50 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: supersuper1231@outlook.com
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/10/lo-interfaces.html
Description:
I assume "inv_oid = lo_creat(conn, INV_READ|INV_WRITE);" should be "inv_oid
= lo_create(conn, INV_READ|INV_WRITE);", right?
https://www.postgresql.org/docs/10/lo-interfaces.html#LO-CREATE
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: documentation typo
@ 2022-01-30 12:44 Magnus Hagander <magnus@hagander.net>
parent: PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 6+ messages in thread
From: Magnus Hagander @ 2022-01-30 12:44 UTC (permalink / raw)
To: supersuper1231@outlook.com; pgsql-docs@lists.postgresql.org
On Sun, Jan 30, 2022 at 1:39 PM PG Doc comments form
<noreply@postgresql.org> wrote:
>
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/10/lo-interfaces.html
> Description:
>
> I assume "inv_oid = lo_creat(conn, INV_READ|INV_WRITE);" should be "inv_oid
> = lo_create(conn, INV_READ|INV_WRITE);", right?
> https://www.postgresql.org/docs/10/lo-interfaces.html#LO-CREATE
lo_creat() and lo_create() are two different functions. They do the
same thing but take different parameters.
It might be worth splitting that part into one section with the
current function (lo_create) and then a separate section with the
backwards-compatible lo_creat function though -- I can see how it's
easy to come to the conclusion you did from reading it, and that could
be made a lot more clear.
--
Magnus Hagander
Me: https://www.hagander.net/
Work: https://www.redpill-linpro.com/
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: documentation typo
@ 2022-01-30 15:52 Tom Lane <tgl@sss.pgh.pa.us>
parent: Magnus Hagander <magnus@hagander.net>
0 siblings, 1 reply; 6+ messages in thread
From: Tom Lane @ 2022-01-30 15:52 UTC (permalink / raw)
To: Magnus Hagander <magnus@hagander.net>; +Cc: supersuper1231@outlook.com; pgsql-docs@lists.postgresql.org
Magnus Hagander <magnus@hagander.net> writes:
> It might be worth splitting that part into one section with the
> current function (lo_create) and then a separate section with the
> backwards-compatible lo_creat function though -- I can see how it's
> easy to come to the conclusion you did from reading it, and that could
> be made a lot more clear.
I dunno, the section already makes it perfectly clear that there
are two functions. I could get behind documenting the more modern
one first, though.
I wonder if it's time to remove the references to PG 8.1?
regards, tom lane
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: documentation typo
@ 2022-01-31 10:53 Daniel Gustafsson <daniel@yesql.se>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 6+ messages in thread
From: Daniel Gustafsson @ 2022-01-31 10:53 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Magnus Hagander <magnus@hagander.net>; supersuper1231@outlook.com; pgsql-docs@lists.postgresql.org
> 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
> 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.
--
Daniel Gustafsson https://vmware.com/
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: documentation typo
@ 2022-01-31 22:05 Tom Lane <tgl@sss.pgh.pa.us>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 6+ messages in thread
From: Tom Lane @ 2022-01-31 22:05 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Magnus Hagander <magnus@hagander.net>; supersuper1231@outlook.com; pgsql-docs@lists.postgresql.org
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.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="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>
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: documentation typo
@ 2022-01-31 22:12 Daniel Gustafsson <daniel@yesql.se>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 6+ messages in thread
From: Daniel Gustafsson @ 2022-01-31 22:12 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Magnus Hagander <magnus@hagander.net>; supersuper1231@outlook.com; pgsql-docs@lists.postgresql.org
> On 31 Jan 2022, at 23:05, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> 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.
Agreed, makes sense.
> Comments?
LGTM.
--
Daniel Gustafsson https://vmware.com/
^ permalink raw reply [nested|flat] 6+ messages in thread
end of thread, other threads:[~2022-01-31 22:12 UTC | newest]
Thread overview: 6+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2022-01-30 08:50 documentation typo PG Doc comments form <noreply@postgresql.org>
2022-01-30 12:44 ` Magnus Hagander <magnus@hagander.net>
2022-01-30 15:52 ` Tom Lane <tgl@sss.pgh.pa.us>
2022-01-31 10:53 ` Daniel Gustafsson <daniel@yesql.se>
2022-01-31 22:05 ` Tom Lane <tgl@sss.pgh.pa.us>
2022-01-31 22:12 ` Daniel Gustafsson <daniel@yesql.se>
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