begriffs open source - ai-pg/blob - full-docs/src/sgml/html/lo-interfaces.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>33.3. Client Interfaces</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="lo-implementation.html" title="33.2. Implementation Features" /><link rel="next" href="lo-funcs.html" title="33.4. Server-Side Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">33.3. Client Interfaces</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="lo-implementation.html" title="33.2. Implementation Features">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="largeobjects.html" title="Chapter 33. Large Objects">Up</a></td><th width="60%" align="center">Chapter 33. Large Objects</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="lo-funcs.html" title="33.4. Server-Side Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="LO-INTERFACES"><div class="titlepage"><div><div><h2 class="title" style="clear: both">33.3. Client Interfaces <a href="#LO-INTERFACES" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="lo-interfaces.html#LO-CREATE">33.3.1. Creating a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-IMPORT">33.3.2. Importing a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-EXPORT">33.3.3. Exporting a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-OPEN">33.3.4. Opening an Existing Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-WRITE">33.3.5. Writing Data to a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-READ">33.3.6. Reading Data from a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-SEEK">33.3.7. Seeking in a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-TELL">33.3.8. Obtaining the Seek Position of a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-TRUNCATE">33.3.9. Truncating a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-CLOSE">33.3.10. Closing a Large Object Descriptor</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-UNLINK">33.3.11. Removing a Large Object</a></span></dt></dl></div><p>
   3     This section describes the facilities that
   4     <span class="productname">PostgreSQL</span>'s <span class="application">libpq</span>
   5     client interface library provides for accessing large objects.
   6     The <span class="productname">PostgreSQL</span> large object interface is
   7     modeled after the <acronym class="acronym">Unix</acronym> file-system interface, with
   8     analogues of <code class="function">open</code>,  <code class="function">read</code>,
   9     <code class="function">write</code>,
  10     <code class="function">lseek</code>, etc.
  11    </p><p>
  12     All large object manipulation using these functions
  13     <span class="emphasis"><em>must</em></span> take place within an SQL transaction block,
  14     since large object file descriptors are only valid for the duration of
  15     a transaction. Write operations, including <code class="function">lo_open</code>
  16     with the <code class="symbol">INV_WRITE</code> mode, are not allowed in a read-only
  17     transaction.
  18    </p><p>
  19     If an error occurs while executing any one of these functions, the
  20     function will return an otherwise-impossible value, typically 0 or -1.
  21     A message describing the error is stored in the connection object and
  22     can be retrieved with <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE">
  23       <code class="function">PQerrorMessage</code>
  24
  25      </a>.
  26    </p><p>
  27     Client applications that use these functions should include the header file
  28     <code class="filename">libpq/libpq-fs.h</code> and link with the
  29     <span class="application">libpq</span> library.
  30    </p><p>
  31     Client applications cannot use these functions while a libpq connection is in pipeline mode.
  32    </p><div class="sect2" id="LO-CREATE"><div class="titlepage"><div><div><h3 class="title">33.3.1. Creating a Large Object <a href="#LO-CREATE" class="id_link">#</a></h3></div></div></div><p>
  33      <a id="id-1.7.4.8.7.2.1" class="indexterm"></a>
  34      The function
  35 </p><pre class="synopsis">
  36 Oid lo_create(PGconn *conn, Oid lobjId);
  37 </pre><p>
  38      creates a new large object.  The OID to be assigned can be
  39      specified by <em class="replaceable"><code>lobjId</code></em>;
  40      if so, failure occurs if that OID is already in use for some large
  41      object.  If <em class="replaceable"><code>lobjId</code></em>
  42      is <code class="symbol">InvalidOid</code> (zero) then <code class="function">lo_create</code>
  43      assigns an unused OID.
  44      The return value is the OID that was assigned to the new large object,
  45      or <code class="symbol">InvalidOid</code> (zero) on failure.
  46     </p><p>
  47      An example:
  48 </p><pre class="programlisting">
  49 inv_oid = lo_create(conn, desired_oid);
  50 </pre><p>
  51     </p><p>
  52      <a id="id-1.7.4.8.7.4.1" class="indexterm"></a>
  53      The older function
  54 </p><pre class="synopsis">
  55 Oid lo_creat(PGconn *conn, int mode);
  56 </pre><p>
  57      also creates a new large object, always assigning an unused OID.
  58      The return value is the OID that was assigned to the new large object,
  59      or <code class="symbol">InvalidOid</code> (zero) on failure.
  60     </p><p>
  61      In <span class="productname">PostgreSQL</span> releases 8.1 and later,
  62      the <em class="replaceable"><code>mode</code></em> is ignored,
  63      so that <code class="function">lo_creat</code> is exactly equivalent to
  64      <code class="function">lo_create</code> with a zero second argument.
  65      However, there is little reason to use <code class="function">lo_creat</code>
  66      unless you need to work with servers older than 8.1.
  67      To work with such an old server, you must
  68      use <code class="function">lo_creat</code> not <code class="function">lo_create</code>,
  69      and you must set <em class="replaceable"><code>mode</code></em> to
  70      one of <code class="symbol">INV_READ</code>, <code class="symbol">INV_WRITE</code>,
  71      or <code class="symbol">INV_READ</code> <code class="literal">|</code> <code class="symbol">INV_WRITE</code>.
  72      (These symbolic constants are defined
  73      in the header file <code class="filename">libpq/libpq-fs.h</code>.)
  74     </p><p>
  75      An example:
  76 </p><pre class="programlisting">
  77 inv_oid = lo_creat(conn, INV_READ|INV_WRITE);
  78 </pre><p>
  79     </p></div><div class="sect2" id="LO-IMPORT"><div class="titlepage"><div><div><h3 class="title">33.3.2. Importing a Large Object <a href="#LO-IMPORT" class="id_link">#</a></h3></div></div></div><p>
  80      <a id="id-1.7.4.8.8.2.1" class="indexterm"></a>
  81      To import an operating system file as a large object, call
  82 </p><pre class="synopsis">
  83 Oid lo_import(PGconn *conn, const char *filename);
  84 </pre><p>
  85      <em class="replaceable"><code>filename</code></em>
  86      specifies the operating system name of
  87      the file to be imported as a large object.
  88      The return value is the OID that was assigned to the new large object,
  89      or <code class="symbol">InvalidOid</code> (zero) on failure.
  90      Note that the file is read by the client interface library, not by
  91      the server; so it must exist in the client file system and be readable
  92      by the client application.
  93     </p><p>
  94      <a id="id-1.7.4.8.8.3.1" class="indexterm"></a>
  95      The function
  96 </p><pre class="synopsis">
  97 Oid lo_import_with_oid(PGconn *conn, const char *filename, Oid lobjId);
  98 </pre><p>
  99      also imports a new large object.  The OID to be assigned can be
 100      specified by <em class="replaceable"><code>lobjId</code></em>;
 101      if so, failure occurs if that OID is already in use for some large
 102      object.  If <em class="replaceable"><code>lobjId</code></em>
 103      is <code class="symbol">InvalidOid</code> (zero) then <code class="function">lo_import_with_oid</code> assigns an unused
 104      OID (this is the same behavior as <code class="function">lo_import</code>).
 105      The return value is the OID that was assigned to the new large object,
 106      or <code class="symbol">InvalidOid</code> (zero) on failure.
 107     </p><p>
 108      <code class="function">lo_import_with_oid</code> is new as of <span class="productname">PostgreSQL</span>
 109      8.4 and uses <code class="function">lo_create</code> internally which is new in 8.1; if this function is run against 8.0 or before, it will
 110      fail and return <code class="symbol">InvalidOid</code>.
 111     </p></div><div class="sect2" id="LO-EXPORT"><div class="titlepage"><div><div><h3 class="title">33.3.3. Exporting a Large Object <a href="#LO-EXPORT" class="id_link">#</a></h3></div></div></div><p>
 112      <a id="id-1.7.4.8.9.2.1" class="indexterm"></a>
 113      To export a large object
 114      into an operating system file, call
 115 </p><pre class="synopsis">
 116 int lo_export(PGconn *conn, Oid lobjId, const char *filename);
 117 </pre><p>
 118      The <em class="parameter"><code>lobjId</code></em> argument specifies the OID of the large
 119      object to export and the <em class="parameter"><code>filename</code></em> argument
 120      specifies the operating system name of the file.  Note that the file is
 121      written by the client interface library, not by the server.  Returns 1
 122      on success, -1 on failure.
 123     </p></div><div class="sect2" id="LO-OPEN"><div class="titlepage"><div><div><h3 class="title">33.3.4. Opening an Existing Large Object <a href="#LO-OPEN" class="id_link">#</a></h3></div></div></div><p>
 124      <a id="id-1.7.4.8.10.2.1" class="indexterm"></a>
 125      To open an existing large object for reading or writing, call
 126 </p><pre class="synopsis">
 127 int lo_open(PGconn *conn, Oid lobjId, int mode);
 128 </pre><p>
 129      The <em class="parameter"><code>lobjId</code></em> argument specifies the OID of the large
 130      object to open.   The <em class="parameter"><code>mode</code></em> bits control whether the
 131      object is opened for reading (<code class="symbol">INV_READ</code>), writing
 132      (<code class="symbol">INV_WRITE</code>), or both.
 133      (These symbolic constants are defined
 134      in the header file <code class="filename">libpq/libpq-fs.h</code>.)
 135      <code class="function">lo_open</code> returns a (non-negative) large object
 136      descriptor for later use in <code class="function">lo_read</code>,
 137      <code class="function">lo_write</code>, <code class="function">lo_lseek</code>,
 138      <code class="function">lo_lseek64</code>, <code class="function">lo_tell</code>,
 139      <code class="function">lo_tell64</code>, <code class="function">lo_truncate</code>,
 140      <code class="function">lo_truncate64</code>, and <code class="function">lo_close</code>.
 141      The descriptor is only valid for
 142      the duration of the current transaction.
 143      On failure, -1 is returned.
 144     </p><p>
 145      The server currently does not distinguish between modes
 146      <code class="symbol">INV_WRITE</code> and <code class="symbol">INV_READ</code> <code class="literal">|</code>
 147      <code class="symbol">INV_WRITE</code>: you are allowed to read from the descriptor
 148      in either case.  However there is a significant difference between
 149      these modes and <code class="symbol">INV_READ</code> alone: with <code class="symbol">INV_READ</code>
 150      you cannot write on the descriptor, and the data read from it will
 151      reflect the contents of the large object at the time of the transaction
 152      snapshot that was active when <code class="function">lo_open</code> was executed,
 153      regardless of later writes by this or other transactions.  Reading
 154      from a descriptor opened with <code class="symbol">INV_WRITE</code> returns
 155      data that reflects all writes of other committed transactions as well
 156      as writes of the current transaction.  This is similar to the behavior
 157      of <code class="literal">REPEATABLE READ</code> versus <code class="literal">READ COMMITTED</code> transaction
 158      modes for ordinary SQL <code class="command">SELECT</code> commands.
 159     </p><p>
 160      <code class="function">lo_open</code> will fail if <code class="literal">SELECT</code>
 161      privilege is not available for the large object, or
 162      if <code class="symbol">INV_WRITE</code> is specified and <code class="literal">UPDATE</code>
 163      privilege is not available.
 164      (Prior to <span class="productname">PostgreSQL</span> 11, these privilege
 165      checks were instead performed at the first actual read or write call
 166      using the descriptor.)
 167      These privilege checks can be disabled with the
 168      <a class="xref" href="runtime-config-compatible.html#GUC-LO-COMPAT-PRIVILEGES">lo_compat_privileges</a> run-time parameter.
 169     </p><p>
 170      An example:
 171 </p><pre class="programlisting">
 172 inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE);
 173 </pre><p>
 174     </p></div><div class="sect2" id="LO-WRITE"><div class="titlepage"><div><div><h3 class="title">33.3.5. Writing Data to a Large Object <a href="#LO-WRITE" class="id_link">#</a></h3></div></div></div><p>
 175      <a id="id-1.7.4.8.11.2.1" class="indexterm"></a>
 176      The function
 177 </p><pre class="synopsis">
 178 int lo_write(PGconn *conn, int fd, const char *buf, size_t len);
 179 </pre><p>
 180      writes <em class="parameter"><code>len</code></em> bytes from <em class="parameter"><code>buf</code></em>
 181      (which must be of size <em class="parameter"><code>len</code></em>) to large object
 182      descriptor <em class="parameter"><code>fd</code></em>.  The <em class="parameter"><code>fd</code></em> argument must
 183      have been returned by a previous <code class="function">lo_open</code>.  The
 184      number of bytes actually written is returned (in the current
 185      implementation, this will always equal <em class="parameter"><code>len</code></em> unless
 186      there is an error).  In the event of an error, the return value is -1.
 187 </p><p>
 188      Although the <em class="parameter"><code>len</code></em> parameter is declared as
 189      <code class="type">size_t</code>, this function will reject length values larger than
 190      <code class="literal">INT_MAX</code>.  In practice, it's best to transfer data in chunks
 191      of at most a few megabytes anyway.
 192 </p></div><div class="sect2" id="LO-READ"><div class="titlepage"><div><div><h3 class="title">33.3.6. Reading Data from a Large Object <a href="#LO-READ" class="id_link">#</a></h3></div></div></div><p>
 193      <a id="id-1.7.4.8.12.2.1" class="indexterm"></a>
 194      The function
 195 </p><pre class="synopsis">
 196 int lo_read(PGconn *conn, int fd, char *buf, size_t len);
 197 </pre><p>
 198      reads up to <em class="parameter"><code>len</code></em> bytes from large object descriptor
 199      <em class="parameter"><code>fd</code></em> into <em class="parameter"><code>buf</code></em> (which must be
 200      of size <em class="parameter"><code>len</code></em>).  The <em class="parameter"><code>fd</code></em>
 201      argument must have been returned by a previous
 202      <code class="function">lo_open</code>.  The number of bytes actually read is
 203      returned; this will be less than <em class="parameter"><code>len</code></em> if the end of
 204      the large object is reached first.  In the event of an error, the return
 205      value is -1.
 206 </p><p>
 207      Although the <em class="parameter"><code>len</code></em> parameter is declared as
 208      <code class="type">size_t</code>, this function will reject length values larger than
 209      <code class="literal">INT_MAX</code>.  In practice, it's best to transfer data in chunks
 210      of at most a few megabytes anyway.
 211 </p></div><div class="sect2" id="LO-SEEK"><div class="titlepage"><div><div><h3 class="title">33.3.7. Seeking in a Large Object <a href="#LO-SEEK" class="id_link">#</a></h3></div></div></div><p>
 212      <a id="id-1.7.4.8.13.2.1" class="indexterm"></a>
 213      To change the current read or write location associated with a
 214      large object descriptor, call
 215 </p><pre class="synopsis">
 216 int lo_lseek(PGconn *conn, int fd, int offset, int whence);
 217 </pre><p>
 218      This function moves the
 219      current location pointer for the large object descriptor identified by
 220      <em class="parameter"><code>fd</code></em> to the new location specified by
 221      <em class="parameter"><code>offset</code></em>.  The valid values for <em class="parameter"><code>whence</code></em>
 222      are <code class="symbol">SEEK_SET</code> (seek from object start),
 223      <code class="symbol">SEEK_CUR</code> (seek from current position), and
 224      <code class="symbol">SEEK_END</code> (seek from object end).  The return value is
 225      the new location pointer, or -1 on error.
 226 </p><p>
 227      <a id="id-1.7.4.8.13.3.1" class="indexterm"></a>
 228      When dealing with large objects that might exceed 2GB in size,
 229      instead use
 230 </p><pre class="synopsis">
 231 int64_t lo_lseek64(PGconn *conn, int fd, int64_t offset, int whence);
 232 </pre><p>
 233      This function has the same behavior
 234      as <code class="function">lo_lseek</code>, but it can accept an
 235      <em class="parameter"><code>offset</code></em> larger than 2GB and/or deliver a result larger
 236      than 2GB.
 237      Note that <code class="function">lo_lseek</code> will fail if the new location
 238      pointer would be greater than 2GB.
 239 </p><p>
 240      <code class="function">lo_lseek64</code> is new as of <span class="productname">PostgreSQL</span>
 241      9.3.  If this function is run against an older server version, it will
 242      fail and return -1.
 243 </p></div><div class="sect2" id="LO-TELL"><div class="titlepage"><div><div><h3 class="title">33.3.8. Obtaining the Seek Position of a Large Object <a href="#LO-TELL" class="id_link">#</a></h3></div></div></div><p>
 244      <a id="id-1.7.4.8.14.2.1" class="indexterm"></a>
 245      To obtain the current read or write location of a large object descriptor,
 246      call
 247 </p><pre class="synopsis">
 248 int lo_tell(PGconn *conn, int fd);
 249 </pre><p>
 250      If there is an error, the return value is -1.
 251 </p><p>
 252      <a id="id-1.7.4.8.14.3.1" class="indexterm"></a>
 253      When dealing with large objects that might exceed 2GB in size,
 254      instead use
 255 </p><pre class="synopsis">
 256 int64_t lo_tell64(PGconn *conn, int fd);
 257 </pre><p>
 258      This function has the same behavior
 259      as <code class="function">lo_tell</code>, but it can deliver a result larger
 260      than 2GB.
 261      Note that <code class="function">lo_tell</code> will fail if the current
 262      read/write location is greater than 2GB.
 263 </p><p>
 264      <code class="function">lo_tell64</code> is new as of <span class="productname">PostgreSQL</span>
 265      9.3.  If this function is run against an older server version, it will
 266      fail and return -1.
 267 </p></div><div class="sect2" id="LO-TRUNCATE"><div class="titlepage"><div><div><h3 class="title">33.3.9. Truncating a Large Object <a href="#LO-TRUNCATE" class="id_link">#</a></h3></div></div></div><p>
 268      <a id="id-1.7.4.8.15.2.1" class="indexterm"></a>
 269      To truncate a large object to a given length, call
 270 </p><pre class="synopsis">
 271 int lo_truncate(PGconn *conn, int fd, size_t len);
 272 </pre><p>
 273      This function truncates the large object
 274      descriptor <em class="parameter"><code>fd</code></em> to length <em class="parameter"><code>len</code></em>.  The
 275      <em class="parameter"><code>fd</code></em> argument must have been returned by a
 276      previous <code class="function">lo_open</code>.  If <em class="parameter"><code>len</code></em> is
 277      greater than the large object's current length, the large object
 278      is extended to the specified length with null bytes ('\0').
 279      On success, <code class="function">lo_truncate</code> returns
 280      zero.  On error, the return value is -1.
 281 </p><p>
 282      The read/write location associated with the descriptor
 283      <em class="parameter"><code>fd</code></em> is not changed.
 284 </p><p>
 285      Although the <em class="parameter"><code>len</code></em> parameter is declared as
 286      <code class="type">size_t</code>, <code class="function">lo_truncate</code> will reject length
 287      values larger than <code class="literal">INT_MAX</code>.
 288 </p><p>
 289      <a id="id-1.7.4.8.15.5.1" class="indexterm"></a>
 290      When dealing with large objects that might exceed 2GB in size,
 291      instead use
 292 </p><pre class="synopsis">
 293 int lo_truncate64(PGconn *conn, int fd, int64_t len);
 294 </pre><p>
 295      This function has the same
 296      behavior as <code class="function">lo_truncate</code>, but it can accept a
 297      <em class="parameter"><code>len</code></em> value exceeding 2GB.
 298 </p><p>
 299      <code class="function">lo_truncate</code> is new as of <span class="productname">PostgreSQL</span>
 300      8.3; if this function is run against an older server version, it will
 301      fail and return -1.
 302 </p><p>
 303      <code class="function">lo_truncate64</code> is new as of <span class="productname">PostgreSQL</span>
 304      9.3; if this function is run against an older server version, it will
 305      fail and return -1.
 306 </p></div><div class="sect2" id="LO-CLOSE"><div class="titlepage"><div><div><h3 class="title">33.3.10. Closing a Large Object Descriptor <a href="#LO-CLOSE" class="id_link">#</a></h3></div></div></div><p>
 307      <a id="id-1.7.4.8.16.2.1" class="indexterm"></a>
 308      A large object descriptor can be closed by calling
 309 </p><pre class="synopsis">
 310 int lo_close(PGconn *conn, int fd);
 311 </pre><p>
 312      where <em class="parameter"><code>fd</code></em> is a
 313      large object descriptor returned by <code class="function">lo_open</code>.
 314      On success, <code class="function">lo_close</code> returns zero.  On
 315      error, the return value is -1.
 316 </p><p>
 317      Any large  object  descriptors that remain open at the end of a
 318      transaction will be closed automatically.
 319 </p></div><div class="sect2" id="LO-UNLINK"><div class="titlepage"><div><div><h3 class="title">33.3.11. Removing a Large Object <a href="#LO-UNLINK" class="id_link">#</a></h3></div></div></div><p>
 320      <a id="id-1.7.4.8.17.2.1" class="indexterm"></a>
 321      To remove a large object from the database, call
 322 </p><pre class="synopsis">
 323 int lo_unlink(PGconn *conn, Oid lobjId);
 324 </pre><p>
 325      The <em class="parameter"><code>lobjId</code></em> argument specifies the OID of the
 326      large object to remove.  Returns 1 if successful, -1 on failure.
 327     </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="lo-implementation.html" title="33.2. Implementation Features">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="largeobjects.html" title="Chapter 33. Large Objects">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="lo-funcs.html" title="33.4. Server-Side Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">33.2. Implementation Features </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 33.4. Server-Side Functions</td></tr></table></div></body></html>