mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
Tom Lane 2022-02-01 10:57:26 -05:00
parent 0526f2f4c3
commit a5a9d77b8b
1 changed files with 37 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
doc/src/sgml/lobj.sgml
View File

@ -138,19 +138,50 @@
<title>Creating a Large Object</title> <title>Creating a Large Object</title>
<para> <para>
<indexterm><primary>lo_creat</primary></indexterm> <indexterm><primary>lo_create</primary></indexterm>
The function The function
<synopsis> <synopsis>
Oid lo_create(PGconn *conn, Oid lobjId);
</synopsis>
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.
</para>
<para>
An example:
<programlisting>
inv_oid = lo_create(conn, desired_oid);
</programlisting>
</para>
<para>
<indexterm><primary>lo_creat</primary></indexterm>
The older function
<synopsis>
Oid lo_creat(PGconn *conn, int mode); Oid lo_creat(PGconn *conn, int mode);
</synopsis> </synopsis>
creates a new large object. 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, The return value is the OID that was assigned to the new large object,
or <symbol>InvalidOid</symbol> (zero) on failure. or <symbol>InvalidOid</symbol> (zero) on failure.
</para>
<replaceable class="parameter">mode</replaceable> is unused and <para>
ignored as of <productname>PostgreSQL</productname> 8.1; however, for In <productname>PostgreSQL</productname> releases 8.1 and later,
backward compatibility with earlier releases it is best to the <replaceable class="parameter">mode</replaceable> is ignored,
set it to <symbol>INV_READ</symbol>, <symbol>INV_WRITE</symbol>, 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>. or <symbol>INV_READ</symbol> <literal>|</literal> <symbol>INV_WRITE</symbol>.
(These symbolic constants are defined (These symbolic constants are defined
in the header file <filename>libpq/libpq-fs.h</filename>.) in the header file <filename>libpq/libpq-fs.h</filename>.)
@ -160,35 +191,6 @@ Oid lo_creat(PGconn *conn, int mode);
An example: An example:
<programlisting> <programlisting>
inv_oid = lo_creat(conn, INV_READ|INV_WRITE); inv_oid = lo_creat(conn, INV_READ|INV_WRITE);
</programlisting>
</para>
<para>
<indexterm><primary>lo_create</primary></indexterm>
The function
<synopsis>
Oid lo_create(PGconn *conn, Oid lobjId);
</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>).
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>.
</para>
<para>
An example:
<programlisting>
inv_oid = lo_create(conn, desired_oid);
</programlisting> </programlisting>
</para> </para>
</sect2> </sect2>