</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);
</synopsis>
     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>
     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_creat(conn, INV_READ|INV_WRITE);
</programlisting>
    </para>
   </sect2>

   <sect2 id="lo-import">
    <title>Importing a Large Object</title>

    <para>
     <indexterm><primary>lo_import</primary></indexterm>
     To import an operating system file as a large object, call
<synopsis>
Oid lo_import(PGconn *conn, const char *filename);
</synopsis>
     <replaceable class="parameter">filename</replaceable>
     specifies the operating system name of
     the file to be imported as a large object.
     The return value is the OID that was assigned to the new large object,
     or <symbol>InvalidOid</symbol> (zero) on failure.
     Note that the file is read by the client interface library, not by
     the server; so it must exist in the client file system and be readable
     by the client application.
    </para>

    <para>
     <indexterm><primary>lo_import_with_oid</primary></indexterm>
     The function
<synopsis>
Oid lo_import_with_oid(PGconn *conn, const char *filename, Oid lobjId);
</synopsis>
     also imports 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_import_with_oid</function> assigns an unused
     OID (this is the same behavior as <function>lo_import</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_import_with_oid</function> is new as of <productname>PostgreSQL</productname>
     8.4 and uses <function>lo_create</function> internally which is new in 8.1; if this function is run against 8.0 or before, it will
     fail and return <symbol>InvalidOid</symbol>.
    </para>
   </sect2>

   <sect2 id="lo-export">
    <title>Exporting a Large Object</title>

    <para>
     <indexterm><primary>lo_export</primary></indexterm>