branch: elpa/pg
commit 5934b3a7dce508da4320ba0087518d7d5f6facea
Author: Eric Marsden <eric.mars...@risk-engineering.org>
Commit: Eric Marsden <eric.mars...@risk-engineering.org>
Document the large-object functionality
---
doc/src/SUMMARY.md | 1 +
doc/src/large-objects.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 77 insertions(+)
diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md
index ab1e066b5f..449e7cade4 100644
--- a/doc/src/SUMMARY.md
+++ b/doc/src/SUMMARY.md
@@ -10,6 +10,7 @@
- [PostGIS support](./postgis.md)
- [Collation support](./collation.md)
- [The COPY protocol](./copy-protocol.md)
+- [Large objects](./large-objects.md)
- [Using schema-qualified names](./schemas.md)
- [Error handling](./error-handling.md)
- [Special pg-el features](./special-features.md)
diff --git a/doc/src/large-objects.md b/doc/src/large-objects.md
new file mode 100644
index 0000000000..1c92624a6c
--- /dev/null
+++ b/doc/src/large-objects.md
@@ -0,0 +1,76 @@
+# Interacting with large objects
+
+The pg-el library includes support for PostgreSQL's [large object
+functionality](https://www.postgresql.org/docs/current/largeobjects.html).
This provides
+stream-style access to data stored in file-like structures. It allows you to
work with data values
+that do not fit into RAM, by seeking to a particular file position then
reading a subset of the full
+file contents.
+
+This functionality builds on the 64-bit functions in PostgreSQL's large object
API (`lo_lseek64` and
+friends), available from PostgreSQL version 9.3, and can therefore handle
large objects of sizes up
+to 4TB.
+
+The following functions are available:
+
+ (pg-lo-create con &optional mode)
+
+Create a new large object and return its OID. The mode argument is ignored in
PostgreSQL releases
+after v8.1
+
+
+ (pg-lo-open con oid &optional mode)
+
+Open the large object identified by `oid` for reading. Returns a large object
descriptor (which works
+similarly to a Unix file descriptor).
+
+
+ (pg-lo-close con fd)
+
+Close the large object described by `fd`.
+
+
+ (pg-lo-read con fd bytes)
+
+Read `bytes` octets from the large object described by `fd`. The value is
returned as an Emacs Lisp
+string.
+
+
+ (pg-lo-write con fd buf)
+
+Write the contents of `buf` to the large object described by `fd`.
+
+
+ (pg-lo-lseek con fd offset whence)
+
+Seek to position `offset` in the large object designated by `fd`. `whence` can
be `pg-SEEK_SET`
+(seek from object start), `pg-SEEK_CUR` (seek from current position), or
`pg-SEEK_END` (seek from
+object end). `offset` may be a large integer (`int8` type in PostgreSQL; this
function calls the
+PostgreSQL backend function `lo_lseek64`).
+
+
+
+ (pg-lo-tell con fd)
+
+Return the current file position in the large object designated by `fd`.
+
+
+ (pg-lo-truncate con fd len)
+
+Truncate the large object desginated by `fd` to size `len` (in octets).
+
+
+ (pg-lo-unlink con oid)
+
+Unlink the large object identified by `oid`.
+
+
+ (pg-lo-import con filename)
+
+Import the contents of `filename` (which must be accessible by the PostgreSQL
backend on the server
+host) as a large object. Returns the oid of the new object.
+
+
+ (pg-lo-export con oid filename)
+
+Export the content of the large object identified by `oid` to `filename` (a
file path which must be
+writable by the PostgreSQL backend on the server host).
