diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/src/sgml/html/lo-funcs.html | 117 |
1 files changed, 117 insertions, 0 deletions
diff --git a/doc/src/sgml/html/lo-funcs.html b/doc/src/sgml/html/lo-funcs.html new file mode 100644 index 0000000..1a7da53 --- /dev/null +++ b/doc/src/sgml/html/lo-funcs.html @@ -0,0 +1,117 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!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.4. Server-Side Functions</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-interfaces.html" title="35.3. Client Interfaces" /><link rel="next" href="lo-examplesect.html" title="35.5. Example Program" /></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.4. Server-Side Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="lo-interfaces.html" title="35.3. Client Interfaces">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.2 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="lo-examplesect.html" title="35.5. Example Program">Next</a></td></tr></table><hr /></div><div class="sect1" id="LO-FUNCS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">35.4. Server-Side Functions <a href="#LO-FUNCS" class="id_link">#</a></h2></div></div></div><p> + Server-side functions tailored for manipulating large objects from SQL are + listed in <a class="xref" href="lo-funcs.html#LO-FUNCS-TABLE" title="Table 35.1. SQL-Oriented Large Object Functions">Table 35.1</a>. + </p><div class="table" id="LO-FUNCS-TABLE"><p class="title"><strong>Table 35.1. SQL-Oriented Large Object Functions</strong></p><div class="table-contents"><table class="table" summary="SQL-Oriented Large Object Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature"> + Function + </p> + <p> + Description + </p> + <p> + Example(s) + </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature"> + <a id="id-1.7.4.9.3.2.2.1.1.1.1" class="indexterm"></a> + <code class="function">lo_from_bytea</code> ( <em class="parameter"><code>loid</code></em> <code class="type">oid</code>, <em class="parameter"><code>data</code></em> <code class="type">bytea</code> ) + → <code class="returnvalue">oid</code> + </p> + <p> + Creates a large object and stores <em class="parameter"><code>data</code></em> in it. + If <em class="parameter"><code>loid</code></em> is zero then the system will choose a + free OID, otherwise that OID is used (with an error if some large + object already has that OID). On success, the large object's OID is + returned. + </p> + <p> + <code class="literal">lo_from_bytea(0, '\xffffff00')</code> + → <code class="returnvalue">24528</code> + </p></td></tr><tr><td class="func_table_entry"><p class="func_signature"> + <a id="id-1.7.4.9.3.2.2.2.1.1.1" class="indexterm"></a> + <code class="function">lo_put</code> ( <em class="parameter"><code>loid</code></em> <code class="type">oid</code>, <em class="parameter"><code>offset</code></em> <code class="type">bigint</code>, <em class="parameter"><code>data</code></em> <code class="type">bytea</code> ) + → <code class="returnvalue">void</code> + </p> + <p> + Writes <em class="parameter"><code>data</code></em> starting at the given offset within + the large object; the large object is enlarged if necessary. + </p> + <p> + <code class="literal">lo_put(24528, 1, '\xaa')</code> + → <code class="returnvalue"></code> + </p></td></tr><tr><td class="func_table_entry"><p class="func_signature"> + <a id="id-1.7.4.9.3.2.2.3.1.1.1" class="indexterm"></a> + <code class="function">lo_get</code> ( <em class="parameter"><code>loid</code></em> <code class="type">oid</code> [<span class="optional">, <em class="parameter"><code>offset</code></em> <code class="type">bigint</code>, <em class="parameter"><code>length</code></em> <code class="type">integer</code> </span>] ) + → <code class="returnvalue">bytea</code> + </p> + <p> + Extracts the large object's contents, or a substring thereof. + </p> + <p> + <code class="literal">lo_get(24528, 0, 3)</code> + → <code class="returnvalue">\xffaaff</code> + </p></td></tr></tbody></table></div></div><br class="table-break" /><p> + There are additional server-side functions corresponding to each of the + client-side functions described earlier; indeed, for the most part the + client-side functions are simply interfaces to the equivalent server-side + functions. The ones just as convenient to call via SQL commands are + <code class="function">lo_creat</code><a id="id-1.7.4.9.4.2" class="indexterm"></a>, + <code class="function">lo_create</code>, + <code class="function">lo_unlink</code><a id="id-1.7.4.9.4.5" class="indexterm"></a>, + <code class="function">lo_import</code><a id="id-1.7.4.9.4.7" class="indexterm"></a>, and + <code class="function">lo_export</code><a id="id-1.7.4.9.4.9" class="indexterm"></a>. + Here are examples of their use: + +</p><pre class="programlisting"> +CREATE TABLE image ( + name text, + raster oid +); + +SELECT lo_creat(-1); -- returns OID of new, empty large object + +SELECT lo_create(43213); -- attempts to create large object with OID 43213 + +SELECT lo_unlink(173454); -- deletes large object with OID 173454 + +INSERT INTO image (name, raster) + VALUES ('beautiful image', lo_import('/etc/motd')); + +INSERT INTO image (name, raster) -- same as above, but specify OID to use + VALUES ('beautiful image', lo_import('/etc/motd', 68583)); + +SELECT lo_export(image.raster, '/tmp/motd') FROM image + WHERE name = 'beautiful image'; +</pre><p> + </p><p> + The server-side <code class="function">lo_import</code> and + <code class="function">lo_export</code> functions behave considerably differently + from their client-side analogs. These two functions read and write files + in the server's file system, using the permissions of the database's + owning user. Therefore, by default their use is restricted to superusers. + In contrast, the client-side import and export functions read and write + files in the client's file system, using the permissions of the client + program. The client-side functions do not require any database + privileges, except the privilege to read or write the large object in + question. + </p><div class="caution"><h3 class="title">Caution</h3><p> + It is possible to <a class="xref" href="sql-grant.html" title="GRANT"><span class="refentrytitle">GRANT</span></a> use of the + server-side <code class="function">lo_import</code> + and <code class="function">lo_export</code> functions to non-superusers, but + careful consideration of the security implications is required. A + malicious user of such privileges could easily parlay them into becoming + superuser (for example by rewriting server configuration files), or could + attack the rest of the server's file system without bothering to obtain + database superuser privileges as such. <span class="emphasis"><em>Access to roles having + such privilege must therefore be guarded just as carefully as access to + superuser roles.</em></span> Nonetheless, if use of + server-side <code class="function">lo_import</code> + or <code class="function">lo_export</code> is needed for some routine task, it's + safer to use a role with such privileges than one with full superuser + privileges, as that helps to reduce the risk of damage from accidental + errors. + </p></div><p> + The functionality of <code class="function">lo_read</code> and + <code class="function">lo_write</code> is also available via server-side calls, + but the names of the server-side functions differ from the client side + interfaces in that they do not contain underscores. You must call + these functions as <code class="function">loread</code> and <code class="function">lowrite</code>. + </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="lo-interfaces.html" title="35.3. Client Interfaces">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-examplesect.html" title="35.5. Example Program">Next</a></td></tr><tr><td width="40%" align="left" valign="top">35.3. Client Interfaces </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 35.5. Example Program</td></tr></table></div></body></html>
\ No newline at end of file |