branch: elpa/pg
commit 870efb8e48fb7c6529a166b689b7e47261daca3c
Author: Eric Marsden <eric.mars...@risk-engineering.org>
Commit: Eric Marsden <eric.mars...@risk-engineering.org>

    Move documentation of large object functionality to dedicated page
---
 doc/src/API.md           | 72 ------------------------------------------------
 doc/src/large-objects.md | 21 ++++++++------
 2 files changed, 12 insertions(+), 81 deletions(-)

diff --git a/doc/src/API.md b/doc/src/API.md
index a78ab5fd07f..f26c7263d8e 100644
--- a/doc/src/API.md
+++ b/doc/src/API.md
@@ -200,78 +200,6 @@ This function must be called before using the pgvector 
extension. It loads the e
 necessary, and sets up the parsing support for vector datatypes.
 
 
-    (pg-lo-create con . args) -> oid
-
-Create a new large object (BLOB, or binary large object in other DBMSes 
parlance) in the database to
-which we are connected via `CON`. Returns an `OID` (which is represented as an 
elisp integer) which
-will allow you to use the large object. Optional `ARGS` are a Unix-style mode 
string which determines
-the permissions of the newly created large object, one of "r" for read-only 
permission, "w" for
-write-only, "rw" for read+write. Default is "r".
-
-Large-object functions MUST be used within a transaction (see the macro 
`with-pg-transaction`).
-
-
-    (pg-lo-open con oid . args) -> fd
-
-Open a large object whose unique identifier is `OID` (an elisp integer) in the 
database to which we
-are connected via `CON`. Optional `ARGS` is a Unix-style mode string as for 
`pg-lo-create`; which
-defaults to "r" read-only permissions. Returns a file descriptor (an elisp 
integer) which can be
-used in other large-object functions.
-
-
-    (pg-lo-close con fd)
-
-Close the file descriptor `FD` which was associated with a large object. Note 
that this does not
-delete the large object; use `pg-lo-unlink` for that.
-
-
-    (pg-lo-read con fd bytes) -> string
-    
-Read `BYTES` from the file descriptor `FD` which is associated with a large 
object. Return an elisp
-string which should be `BYTES` characters long.
-
-
-    (pg-lo-write con fd buf)
-
-Write the bytes contained in the elisp string `BUF` to the large object 
associated with the file
-descriptor `FD`.
-
-
-    (pg-lo-lseek con fd offset whence)
-
-Do the equivalent of a `lseek(2)` on the file descriptor `FD` which is 
associated with a large
-object; i.e. reposition the read/write file offset for that large object to 
`OFFSET` (an elisp
-integer). `WHENCE` has the same significance as in `lseek()`; it should be one 
of `SEEK_SET` (set the
-offset to the absolute position), `SEEK_CUR` (set the offset relative to the 
current offset) or
-`SEEK_END` (set the offset relative to the end of the file). `WHENCE` should 
be an elisp integer whose
-values can be obtained from the header file `<unistd.h>` (probably 0, 1 and 2 
respectively).
-
-
-    (pg-lo-tell con oid) -> integer
-    
-Do the equivalent of an `ftell(3)` on the file associated with the large 
object whose unique
-identifier is `OID`. Returns the current position of the file offset for the 
object's associated file
-descriptor, as an elisp integer.
-
-
-    (pg-lo-unlink con oid)
-    
-Remove the large object whose unique identifier is `OID` from the system. In 
the current
-implementation of large objects in PostgreSQL, each large object is associated 
with an object in the
-filesystem.
-
-
-    (pg-lo-import con filename) -> oid
-
-Create a new large object and initialize it to the data contained in the file 
whose name is
-`FILENAME`. Returns an `OID` (as an elisp integer). Note that this operation 
is only syntactic sugar
-around the basic large-object operations listed above.
-
-
-    (pg-lo-export con oid filename)
-    
-Create a new file named `FILENAME` and fill it with the contents of the large 
object whose unique
-identifier is `OID`. This operation is also syntactic sugar.
 
 
 Variable `pg-parameter-change-functions` is a list of handlers to be called 
when the backend informs
diff --git a/doc/src/large-objects.md b/doc/src/large-objects.md
index 1c92624a6c2..2370b543fdb 100644
--- a/doc/src/large-objects.md
+++ b/doc/src/large-objects.md
@@ -14,8 +14,10 @@ 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
+Create a new large object and return its OID (represented in elisp by an 
integer). The mode argument
+is ignored in PostgreSQL releases after v8.1.
+
+Large-object functions MUST be used within a transaction (see the macro 
`with-pg-transaction`).
 
 
     (pg-lo-open con oid &optional mode)
@@ -25,8 +27,9 @@ similarly to a Unix file descriptor).
 
 
     (pg-lo-close con fd)
-    
-Close the large object described by `fd`.
+
+Close the large object described by `fd`. Note that this does not delete the 
large object; use
+`pg-lo-unlink` for that.
 
 
     (pg-lo-read con fd bytes)
@@ -37,7 +40,7 @@ string.
 
     (pg-lo-write con fd buf)
     
-Write the contents of `buf` to the large object described by `fd`.
+Write the contents of the elisp string `buf` to the large object described by 
`fd`.
 
 
     (pg-lo-lseek con fd offset whence)
@@ -45,13 +48,13 @@ Write the contents of `buf` to the large object described 
by `fd`.
 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`).
-
+PostgreSQL backend function `lo_lseek64`). This function works in the same was 
as `lseek(2)` in Unix.
 
 
     (pg-lo-tell con fd)
     
-Return the current file position in the large object designated by `fd`.
+Return the current file position in the large object designated by `fd`. This 
function works in the
+same was as `ftell(3)` in Unix.
 
 
     (pg-lo-truncate con fd len)
@@ -61,7 +64,7 @@ Truncate the large object desginated by `fd` to size `len` 
(in octets).
 
     (pg-lo-unlink con oid)
     
-Unlink the large object identified by `oid`.
+Unlink (remove from the filesystem) the large object identified by `oid`.
 
 
     (pg-lo-import con filename)

Reply via email to