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)