codekingpro/portable-devtools
115k
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>35.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="35.2. Implementation Features" /><link rel="next" href="lo-funcs.html" title="35.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">35.3. Client Interfaces</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="lo-implementation.html" title="35.2. Implementation Features">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="largeobjects.html" title="Chapter 35. Large Objects">Up</a></td><th width="60%" align="center">Chapter 35. Large Objects</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="lo-funcs.html" title="35.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">35.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">35.3.1. Creating a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-IMPORT">35.3.2. Importing a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-EXPORT">35.3.3. Exporting a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-OPEN">35.3.4. Opening an Existing Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-WRITE">35.3.5. Writing Data to a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-READ">35.3.6. Reading Data from a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-SEEK">35.3.7. Seeking in a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-TELL">35.3.8. Obtaining the Seek Position of a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-TRUNCATE">35.3.9. Truncating a Large Object</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-CLOSE">35.3.10. Closing a Large Object Descriptor</a></span></dt><dt><span class="sect2"><a href="lo-interfaces.html#LO-UNLINK">35.3.11. Removing a Large Object</a></span></dt></dl></div><p>3 This section describes the facilities that4 <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 is7 modeled after the <acronym class="acronym">Unix</acronym> file-system interface, with8 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 functions13 <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 of15 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-only17 transaction.18 </p><p>19 If an error occurs while executing any one of these functions, the20 function will return an otherwise-impossible value, typically 0 or -1.21 A message describing the error is stored in the connection object and22 can be retrieved with <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a>.23 </p><p>24 Client applications that use these functions should include the header file25 <code class="filename">libpq/libpq-fs.h</code> and link with the26 <span class="application">libpq</span> library.27 </p><p>28 Client applications cannot use these functions while a libpq connection is in pipeline mode.29 </p><div class="sect2" id="LO-CREATE"><div class="titlepage"><div><div><h3 class="title">35.3.1. Creating a Large Object <a href="#LO-CREATE" class="id_link">#</a></h3></div></div></div><p>30 <a id="id-1.7.4.8.7.2.1" class="indexterm"></a>31 The function32</p><pre class="synopsis">33Oid lo_create(PGconn *conn, Oid lobjId);34</pre><p>35 creates a new large object. The OID to be assigned can be36 specified by <em class="replaceable"><code>lobjId</code></em>;37 if so, failure occurs if that OID is already in use for some large38 object. If <em class="replaceable"><code>lobjId</code></em>39 is <code class="symbol">InvalidOid</code> (zero) then <code class="function">lo_create</code>40 assigns an unused OID.41 The return value is the OID that was assigned to the new large object,42 or <code class="symbol">InvalidOid</code> (zero) on failure.43 </p><p>44 An example:45</p><pre class="programlisting">46inv_oid = lo_create(conn, desired_oid);47</pre><p>48 </p><p>49 <a id="id-1.7.4.8.7.4.1" class="indexterm"></a>50 The older function51</p><pre class="synopsis">52Oid lo_creat(PGconn *conn, int mode);53</pre><p>54 also creates a new large object, always assigning an unused OID.55 The return value is the OID that was assigned to the new large object,56 or <code class="symbol">InvalidOid</code> (zero) on failure.57 </p><p>58 In <span class="productname">PostgreSQL</span> releases 8.1 and later,59 the <em class="replaceable"><code>mode</code></em> is ignored,60 so that <code class="function">lo_creat</code> is exactly equivalent to61 <code class="function">lo_create</code> with a zero second argument.62 However, there is little reason to use <code class="function">lo_creat</code>63 unless you need to work with servers older than 8.1.64 To work with such an old server, you must65 use <code class="function">lo_creat</code> not <code class="function">lo_create</code>,66 and you must set <em class="replaceable"><code>mode</code></em> to67 one of <code class="symbol">INV_READ</code>, <code class="symbol">INV_WRITE</code>,68 or <code class="symbol">INV_READ</code> <code class="literal">|</code> <code class="symbol">INV_WRITE</code>.69 (These symbolic constants are defined70 in the header file <code class="filename">libpq/libpq-fs.h</code>.)71 </p><p>72 An example:73</p><pre class="programlisting">74inv_oid = lo_creat(conn, INV_READ|INV_WRITE);75</pre><p>76 </p></div><div class="sect2" id="LO-IMPORT"><div class="titlepage"><div><div><h3 class="title">35.3.2. Importing a Large Object <a href="#LO-IMPORT" class="id_link">#</a></h3></div></div></div><p>77 <a id="id-1.7.4.8.8.2.1" class="indexterm"></a>78 To import an operating system file as a large object, call79</p><pre class="synopsis">80Oid lo_import(PGconn *conn, const char *filename);81</pre><p>82 <em class="replaceable"><code>filename</code></em>83 specifies the operating system name of84 the file to be imported as a large object.85 The return value is the OID that was assigned to the new large object,86 or <code class="symbol">InvalidOid</code> (zero) on failure.87 Note that the file is read by the client interface library, not by88 the server; so it must exist in the client file system and be readable89 by the client application.90 </p><p>91 <a id="id-1.7.4.8.8.3.1" class="indexterm"></a>92 The function93</p><pre class="synopsis">94Oid lo_import_with_oid(PGconn *conn, const char *filename, Oid lobjId);95</pre><p>96 also imports a new large object. The OID to be assigned can be97 specified by <em class="replaceable"><code>lobjId</code></em>;98 if so, failure occurs if that OID is already in use for some large99 object. If <em class="replaceable"><code>lobjId</code></em>100 is <code class="symbol">InvalidOid</code> (zero) then <code class="function">lo_import_with_oid</code> assigns an unused101 OID (this is the same behavior as <code class="function">lo_import</code>).102 The return value is the OID that was assigned to the new large object,103 or <code class="symbol">InvalidOid</code> (zero) on failure.104 </p><p>105 <code class="function">lo_import_with_oid</code> is new as of <span class="productname">PostgreSQL</span>106 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 will107 fail and return <code class="symbol">InvalidOid</code>.108 </p></div><div class="sect2" id="LO-EXPORT"><div class="titlepage"><div><div><h3 class="title">35.3.3. Exporting a Large Object <a href="#LO-EXPORT" class="id_link">#</a></h3></div></div></div><p>109 <a id="id-1.7.4.8.9.2.1" class="indexterm"></a>110 To export a large object111 into an operating system file, call112</p><pre class="synopsis">113int lo_export(PGconn *conn, Oid lobjId, const char *filename);114</pre><p>115 The <em class="parameter"><code>lobjId</code></em> argument specifies the OID of the large116 object to export and the <em class="parameter"><code>filename</code></em> argument117 specifies the operating system name of the file. Note that the file is118 written by the client interface library, not by the server. Returns 1119 on success, -1 on failure.120 </p></div><div class="sect2" id="LO-OPEN"><div class="titlepage"><div><div><h3 class="title">35.3.4. Opening an Existing Large Object <a href="#LO-OPEN" class="id_link">#</a></h3></div></div></div><p>121 <a id="id-1.7.4.8.10.2.1" class="indexterm"></a>122 To open an existing large object for reading or writing, call123</p><pre class="synopsis">124int lo_open(PGconn *conn, Oid lobjId, int mode);125</pre><p>126 The <em class="parameter"><code>lobjId</code></em> argument specifies the OID of the large127 object to open. The <em class="parameter"><code>mode</code></em> bits control whether the128 object is opened for reading (<code class="symbol">INV_READ</code>), writing129 (<code class="symbol">INV_WRITE</code>), or both.130 (These symbolic constants are defined131 in the header file <code class="filename">libpq/libpq-fs.h</code>.)132 <code class="function">lo_open</code> returns a (non-negative) large object133 descriptor for later use in <code class="function">lo_read</code>,134 <code class="function">lo_write</code>, <code class="function">lo_lseek</code>,135 <code class="function">lo_lseek64</code>, <code class="function">lo_tell</code>,136 <code class="function">lo_tell64</code>, <code class="function">lo_truncate</code>,137 <code class="function">lo_truncate64</code>, and <code class="function">lo_close</code>.138 The descriptor is only valid for139 the duration of the current transaction.140 On failure, -1 is returned.141 </p><p>142 The server currently does not distinguish between modes143 <code class="symbol">INV_WRITE</code> and <code class="symbol">INV_READ</code> <code class="literal">|</code>144 <code class="symbol">INV_WRITE</code>: you are allowed to read from the descriptor145 in either case. However there is a significant difference between146 these modes and <code class="symbol">INV_READ</code> alone: with <code class="symbol">INV_READ</code>147 you cannot write on the descriptor, and the data read from it will148 reflect the contents of the large object at the time of the transaction149 snapshot that was active when <code class="function">lo_open</code> was executed,150 regardless of later writes by this or other transactions. Reading151 from a descriptor opened with <code class="symbol">INV_WRITE</code> returns152 data that reflects all writes of other committed transactions as well153 as writes of the current transaction. This is similar to the behavior154 of <code class="literal">REPEATABLE READ</code> versus <code class="literal">READ COMMITTED</code> transaction155 modes for ordinary SQL <code class="command">SELECT</code> commands.156 </p><p>157 <code class="function">lo_open</code> will fail if <code class="literal">SELECT</code>158 privilege is not available for the large object, or159 if <code class="symbol">INV_WRITE</code> is specified and <code class="literal">UPDATE</code>160 privilege is not available.161 (Prior to <span class="productname">PostgreSQL</span> 11, these privilege162 checks were instead performed at the first actual read or write call163 using the descriptor.)164 These privilege checks can be disabled with the165 <a class="xref" href="runtime-config-compatible.html#GUC-LO-COMPAT-PRIVILEGES">lo_compat_privileges</a> run-time parameter.166 </p><p>167 An example:168</p><pre class="programlisting">169inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE);170</pre><p>171 </p></div><div class="sect2" id="LO-WRITE"><div class="titlepage"><div><div><h3 class="title">35.3.5. Writing Data to a Large Object <a href="#LO-WRITE" class="id_link">#</a></h3></div></div></div><p>172 <a id="id-1.7.4.8.11.2.1" class="indexterm"></a>173 The function174</p><pre class="synopsis">175int lo_write(PGconn *conn, int fd, const char *buf, size_t len);176</pre><p>177 writes <em class="parameter"><code>len</code></em> bytes from <em class="parameter"><code>buf</code></em>178 (which must be of size <em class="parameter"><code>len</code></em>) to large object179 descriptor <em class="parameter"><code>fd</code></em>. The <em class="parameter"><code>fd</code></em> argument must180 have been returned by a previous <code class="function">lo_open</code>. The181 number of bytes actually written is returned (in the current182 implementation, this will always equal <em class="parameter"><code>len</code></em> unless183 there is an error). In the event of an error, the return value is -1.184</p><p>185 Although the <em class="parameter"><code>len</code></em> parameter is declared as186 <code class="type">size_t</code>, this function will reject length values larger than187 <code class="literal">INT_MAX</code>. In practice, it's best to transfer data in chunks188 of at most a few megabytes anyway.189</p></div><div class="sect2" id="LO-READ"><div class="titlepage"><div><div><h3 class="title">35.3.6. Reading Data from a Large Object <a href="#LO-READ" class="id_link">#</a></h3></div></div></div><p>190 <a id="id-1.7.4.8.12.2.1" class="indexterm"></a>191 The function192</p><pre class="synopsis">193int lo_read(PGconn *conn, int fd, char *buf, size_t len);194</pre><p>195 reads up to <em class="parameter"><code>len</code></em> bytes from large object descriptor196 <em class="parameter"><code>fd</code></em> into <em class="parameter"><code>buf</code></em> (which must be197 of size <em class="parameter"><code>len</code></em>). The <em class="parameter"><code>fd</code></em>198 argument must have been returned by a previous199 <code class="function">lo_open</code>. The number of bytes actually read is200 returned; this will be less than <em class="parameter"><code>len</code></em> if the end of201 the large object is reached first. In the event of an error, the return202 value is -1.203</p><p>204 Although the <em class="parameter"><code>len</code></em> parameter is declared as205 <code class="type">size_t</code>, this function will reject length values larger than206 <code class="literal">INT_MAX</code>. In practice, it's best to transfer data in chunks207 of at most a few megabytes anyway.208</p></div><div class="sect2" id="LO-SEEK"><div class="titlepage"><div><div><h3 class="title">35.3.7. Seeking in a Large Object <a href="#LO-SEEK" class="id_link">#</a></h3></div></div></div><p>209 <a id="id-1.7.4.8.13.2.1" class="indexterm"></a>210 To change the current read or write location associated with a211 large object descriptor, call212</p><pre class="synopsis">213int lo_lseek(PGconn *conn, int fd, int offset, int whence);214</pre><p>215 This function moves the216 current location pointer for the large object descriptor identified by217 <em class="parameter"><code>fd</code></em> to the new location specified by218 <em class="parameter"><code>offset</code></em>. The valid values for <em class="parameter"><code>whence</code></em>219 are <code class="symbol">SEEK_SET</code> (seek from object start),220 <code class="symbol">SEEK_CUR</code> (seek from current position), and221 <code class="symbol">SEEK_END</code> (seek from object end). The return value is222 the new location pointer, or -1 on error.223</p><p>224 <a id="id-1.7.4.8.13.3.1" class="indexterm"></a>225 When dealing with large objects that might exceed 2GB in size,226 instead use227</p><pre class="synopsis">228pg_int64 lo_lseek64(PGconn *conn, int fd, pg_int64 offset, int whence);229</pre><p>230 This function has the same behavior231 as <code class="function">lo_lseek</code>, but it can accept an232 <em class="parameter"><code>offset</code></em> larger than 2GB and/or deliver a result larger233 than 2GB.234 Note that <code class="function">lo_lseek</code> will fail if the new location235 pointer would be greater than 2GB.236</p><p>237 <code class="function">lo_lseek64</code> is new as of <span class="productname">PostgreSQL</span>238 9.3. If this function is run against an older server version, it will239 fail and return -1.240</p></div><div class="sect2" id="LO-TELL"><div class="titlepage"><div><div><h3 class="title">35.3.8. Obtaining the Seek Position of a Large Object <a href="#LO-TELL" class="id_link">#</a></h3></div></div></div><p>241 <a id="id-1.7.4.8.14.2.1" class="indexterm"></a>242 To obtain the current read or write location of a large object descriptor,243 call244</p><pre class="synopsis">245int lo_tell(PGconn *conn, int fd);246</pre><p>247 If there is an error, the return value is -1.248</p><p>249 <a id="id-1.7.4.8.14.3.1" class="indexterm"></a>250 When dealing with large objects that might exceed 2GB in size,251 instead use252</p><pre class="synopsis">253pg_int64 lo_tell64(PGconn *conn, int fd);254</pre><p>255 This function has the same behavior256 as <code class="function">lo_tell</code>, but it can deliver a result larger257 than 2GB.258 Note that <code class="function">lo_tell</code> will fail if the current259 read/write location is greater than 2GB.260</p><p>261 <code class="function">lo_tell64</code> is new as of <span class="productname">PostgreSQL</span>262 9.3. If this function is run against an older server version, it will263 fail and return -1.264</p></div><div class="sect2" id="LO-TRUNCATE"><div class="titlepage"><div><div><h3 class="title">35.3.9. Truncating a Large Object <a href="#LO-TRUNCATE" class="id_link">#</a></h3></div></div></div><p>265 <a id="id-1.7.4.8.15.2.1" class="indexterm"></a>266 To truncate a large object to a given length, call267</p><pre class="synopsis">268int lo_truncate(PGconn *conn, int fd, size_t len);269</pre><p>270 This function truncates the large object271 descriptor <em class="parameter"><code>fd</code></em> to length <em class="parameter"><code>len</code></em>. The272 <em class="parameter"><code>fd</code></em> argument must have been returned by a273 previous <code class="function">lo_open</code>. If <em class="parameter"><code>len</code></em> is274 greater than the large object's current length, the large object275 is extended to the specified length with null bytes ('\0').276 On success, <code class="function">lo_truncate</code> returns277 zero. On error, the return value is -1.278</p><p>279 The read/write location associated with the descriptor280 <em class="parameter"><code>fd</code></em> is not changed.281</p><p>282 Although the <em class="parameter"><code>len</code></em> parameter is declared as283 <code class="type">size_t</code>, <code class="function">lo_truncate</code> will reject length284 values larger than <code class="literal">INT_MAX</code>.285</p><p>286 <a id="id-1.7.4.8.15.5.1" class="indexterm"></a>287 When dealing with large objects that might exceed 2GB in size,288 instead use289</p><pre class="synopsis">290int lo_truncate64(PGconn *conn, int fd, pg_int64 len);291</pre><p>292 This function has the same293 behavior as <code class="function">lo_truncate</code>, but it can accept a294 <em class="parameter"><code>len</code></em> value exceeding 2GB.295</p><p>296 <code class="function">lo_truncate</code> is new as of <span class="productname">PostgreSQL</span>297 8.3; if this function is run against an older server version, it will298 fail and return -1.299</p><p>300 <code class="function">lo_truncate64</code> is new as of <span class="productname">PostgreSQL</span>301 9.3; if this function is run against an older server version, it will302 fail and return -1.303</p></div><div class="sect2" id="LO-CLOSE"><div class="titlepage"><div><div><h3 class="title">35.3.10. Closing a Large Object Descriptor <a href="#LO-CLOSE" class="id_link">#</a></h3></div></div></div><p>304 <a id="id-1.7.4.8.16.2.1" class="indexterm"></a>305 A large object descriptor can be closed by calling306</p><pre class="synopsis">307int lo_close(PGconn *conn, int fd);308</pre><p>309 where <em class="parameter"><code>fd</code></em> is a310 large object descriptor returned by <code class="function">lo_open</code>.311 On success, <code class="function">lo_close</code> returns zero. On312 error, the return value is -1.313</p><p>314 Any large object descriptors that remain open at the end of a315 transaction will be closed automatically.316</p></div><div class="sect2" id="LO-UNLINK"><div class="titlepage"><div><div><h3 class="title">35.3.11. Removing a Large Object <a href="#LO-UNLINK" class="id_link">#</a></h3></div></div></div><p>317 <a id="id-1.7.4.8.17.2.1" class="indexterm"></a>318 To remove a large object from the database, call319</p><pre class="synopsis">320int lo_unlink(PGconn *conn, Oid lobjId);321</pre><p>322 The <em class="parameter"><code>lobjId</code></em> argument specifies the OID of the323 large object to remove. Returns 1 if successful, -1 on failure.324 </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="35.2. Implementation Features">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="largeobjects.html" title="Chapter 35. Large Objects">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="lo-funcs.html" title="35.4. Server-Side Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">35.2. Implementation Features </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 35.4. Server-Side Functions</td></tr></table></div></body></html>