begriffs open source - ai-pg/blob - full-docs/txt/lo-interfaces.txt

   1
   2 33.3. Client Interfaces #
   3
   4    33.3.1. Creating a Large Object
   5    33.3.2. Importing a Large Object
   6    33.3.3. Exporting a Large Object
   7    33.3.4. Opening an Existing Large Object
   8    33.3.5. Writing Data to a Large Object
   9    33.3.6. Reading Data from a Large Object
  10    33.3.7. Seeking in a Large Object
  11    33.3.8. Obtaining the Seek Position of a Large Object
  12    33.3.9. Truncating a Large Object
  13    33.3.10. Closing a Large Object Descriptor
  14    33.3.11. Removing a Large Object
  15
  16    This section describes the facilities that PostgreSQL's libpq client
  17    interface library provides for accessing large objects. The PostgreSQL
  18    large object interface is modeled after the Unix file-system interface,
  19    with analogues of open, read, write, lseek, etc.
  20
  21    All large object manipulation using these functions must take place
  22    within an SQL transaction block, since large object file descriptors
  23    are only valid for the duration of a transaction. Write operations,
  24    including lo_open with the INV_WRITE mode, are not allowed in a
  25    read-only transaction.
  26
  27    If an error occurs while executing any one of these functions, the
  28    function will return an otherwise-impossible value, typically 0 or -1.
  29    A message describing the error is stored in the connection object and
  30    can be retrieved with PQerrorMessage .
  31
  32    Client applications that use these functions should include the header
  33    file libpq/libpq-fs.h and link with the libpq library.
  34
  35    Client applications cannot use these functions while a libpq connection
  36    is in pipeline mode.
  37
  38 33.3.1. Creating a Large Object #
  39
  40    The function
  41 Oid lo_create(PGconn *conn, Oid lobjId);
  42
  43    creates a new large object. The OID to be assigned can be specified by
  44    lobjId; if so, failure occurs if that OID is already in use for some
  45    large object. If lobjId is InvalidOid (zero) then lo_create assigns an
  46    unused OID. The return value is the OID that was assigned to the new
  47    large object, or InvalidOid (zero) on failure.
  48
  49    An example:
  50 inv_oid = lo_create(conn, desired_oid);
  51
  52    The older function
  53 Oid lo_creat(PGconn *conn, int mode);
  54
  55    also creates a new large object, always assigning an unused OID. The
  56    return value is the OID that was assigned to the new large object, or
  57    InvalidOid (zero) on failure.
  58
  59    In PostgreSQL releases 8.1 and later, the mode is ignored, so that
  60    lo_creat is exactly equivalent to lo_create with a zero second
  61    argument. However, there is little reason to use lo_creat unless you
  62    need to work with servers older than 8.1. To work with such an old
  63    server, you must use lo_creat not lo_create, and you must set mode to
  64    one of INV_READ, INV_WRITE, or INV_READ | INV_WRITE. (These symbolic
  65    constants are defined in the header file libpq/libpq-fs.h.)
  66
  67    An example:
  68 inv_oid = lo_creat(conn, INV_READ|INV_WRITE);
  69
  70 33.3.2. Importing a Large Object #
  71
  72    To import an operating system file as a large object, call
  73 Oid lo_import(PGconn *conn, const char *filename);
  74
  75    filename specifies the operating system name of the file to be imported
  76    as a large object. The return value is the OID that was assigned to the
  77    new large object, or InvalidOid (zero) on failure. Note that the file
  78    is read by the client interface library, not by the server; so it must
  79    exist in the client file system and be readable by the client
  80    application.
  81
  82    The function
  83 Oid lo_import_with_oid(PGconn *conn, const char *filename, Oid lobjId);
  84
  85    also imports a new large object. The OID to be assigned can be
  86    specified by lobjId; if so, failure occurs if that OID is already in
  87    use for some large object. If lobjId is InvalidOid (zero) then
  88    lo_import_with_oid assigns an unused OID (this is the same behavior as
  89    lo_import). The return value is the OID that was assigned to the new
  90    large object, or InvalidOid (zero) on failure.
  91
  92    lo_import_with_oid is new as of PostgreSQL 8.4 and uses lo_create
  93    internally which is new in 8.1; if this function is run against 8.0 or
  94    before, it will fail and return InvalidOid.
  95
  96 33.3.3. Exporting a Large Object #
  97
  98    To export a large object into an operating system file, call
  99 int lo_export(PGconn *conn, Oid lobjId, const char *filename);
 100
 101    The lobjId argument specifies the OID of the large object to export and
 102    the filename argument specifies the operating system name of the file.
 103    Note that the file is written by the client interface library, not by
 104    the server. Returns 1 on success, -1 on failure.
 105
 106 33.3.4. Opening an Existing Large Object #
 107
 108    To open an existing large object for reading or writing, call
 109 int lo_open(PGconn *conn, Oid lobjId, int mode);
 110
 111    The lobjId argument specifies the OID of the large object to open. The
 112    mode bits control whether the object is opened for reading (INV_READ),
 113    writing (INV_WRITE), or both. (These symbolic constants are defined in
 114    the header file libpq/libpq-fs.h.) lo_open returns a (non-negative)
 115    large object descriptor for later use in lo_read, lo_write, lo_lseek,
 116    lo_lseek64, lo_tell, lo_tell64, lo_truncate, lo_truncate64, and
 117    lo_close. The descriptor is only valid for the duration of the current
 118    transaction. On failure, -1 is returned.
 119
 120    The server currently does not distinguish between modes INV_WRITE and
 121    INV_READ | INV_WRITE: you are allowed to read from the descriptor in
 122    either case. However there is a significant difference between these
 123    modes and INV_READ alone: with INV_READ you cannot write on the
 124    descriptor, and the data read from it will reflect the contents of the
 125    large object at the time of the transaction snapshot that was active
 126    when lo_open was executed, regardless of later writes by this or other
 127    transactions. Reading from a descriptor opened with INV_WRITE returns
 128    data that reflects all writes of other committed transactions as well
 129    as writes of the current transaction. This is similar to the behavior
 130    of REPEATABLE READ versus READ COMMITTED transaction modes for ordinary
 131    SQL SELECT commands.
 132
 133    lo_open will fail if SELECT privilege is not available for the large
 134    object, or if INV_WRITE is specified and UPDATE privilege is not
 135    available. (Prior to PostgreSQL 11, these privilege checks were instead
 136    performed at the first actual read or write call using the descriptor.)
 137    These privilege checks can be disabled with the lo_compat_privileges
 138    run-time parameter.
 139
 140    An example:
 141 inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE);
 142
 143 33.3.5. Writing Data to a Large Object #
 144
 145    The function
 146 int lo_write(PGconn *conn, int fd, const char *buf, size_t len);
 147
 148    writes len bytes from buf (which must be of size len) to large object
 149    descriptor fd. The fd argument must have been returned by a previous
 150    lo_open. The number of bytes actually written is returned (in the
 151    current implementation, this will always equal len unless there is an
 152    error). In the event of an error, the return value is -1.
 153
 154    Although the len parameter is declared as size_t, this function will
 155    reject length values larger than INT_MAX. In practice, it's best to
 156    transfer data in chunks of at most a few megabytes anyway.
 157
 158 33.3.6. Reading Data from a Large Object #
 159
 160    The function
 161 int lo_read(PGconn *conn, int fd, char *buf, size_t len);
 162
 163    reads up to len bytes from large object descriptor fd into buf (which
 164    must be of size len). The fd argument must have been returned by a
 165    previous lo_open. The number of bytes actually read is returned; this
 166    will be less than len if the end of the large object is reached first.
 167    In the event of an error, the return value is -1.
 168
 169    Although the len parameter is declared as size_t, this function will
 170    reject length values larger than INT_MAX. In practice, it's best to
 171    transfer data in chunks of at most a few megabytes anyway.
 172
 173 33.3.7. Seeking in a Large Object #
 174
 175    To change the current read or write location associated with a large
 176    object descriptor, call
 177 int lo_lseek(PGconn *conn, int fd, int offset, int whence);
 178
 179    This function moves the current location pointer for the large object
 180    descriptor identified by fd to the new location specified by offset.
 181    The valid values for whence are SEEK_SET (seek from object start),
 182    SEEK_CUR (seek from current position), and SEEK_END (seek from object
 183    end). The return value is the new location pointer, or -1 on error.
 184
 185    When dealing with large objects that might exceed 2GB in size, instead
 186    use
 187 int64_t lo_lseek64(PGconn *conn, int fd, int64_t offset, int whence);
 188
 189    This function has the same behavior as lo_lseek, but it can accept an
 190    offset larger than 2GB and/or deliver a result larger than 2GB. Note
 191    that lo_lseek will fail if the new location pointer would be greater
 192    than 2GB.
 193
 194    lo_lseek64 is new as of PostgreSQL 9.3. If this function is run against
 195    an older server version, it will fail and return -1.
 196
 197 33.3.8. Obtaining the Seek Position of a Large Object #
 198
 199    To obtain the current read or write location of a large object
 200    descriptor, call
 201 int lo_tell(PGconn *conn, int fd);
 202
 203    If there is an error, the return value is -1.
 204
 205    When dealing with large objects that might exceed 2GB in size, instead
 206    use
 207 int64_t lo_tell64(PGconn *conn, int fd);
 208
 209    This function has the same behavior as lo_tell, but it can deliver a
 210    result larger than 2GB. Note that lo_tell will fail if the current
 211    read/write location is greater than 2GB.
 212
 213    lo_tell64 is new as of PostgreSQL 9.3. If this function is run against
 214    an older server version, it will fail and return -1.
 215
 216 33.3.9. Truncating a Large Object #
 217
 218    To truncate a large object to a given length, call
 219 int lo_truncate(PGconn *conn, int fd, size_t len);
 220
 221    This function truncates the large object descriptor fd to length len.
 222    The fd argument must have been returned by a previous lo_open. If len
 223    is greater than the large object's current length, the large object is
 224    extended to the specified length with null bytes ('\0'). On success,
 225    lo_truncate returns zero. On error, the return value is -1.
 226
 227    The read/write location associated with the descriptor fd is not
 228    changed.
 229
 230    Although the len parameter is declared as size_t, lo_truncate will
 231    reject length values larger than INT_MAX.
 232
 233    When dealing with large objects that might exceed 2GB in size, instead
 234    use
 235 int lo_truncate64(PGconn *conn, int fd, int64_t len);
 236
 237    This function has the same behavior as lo_truncate, but it can accept a
 238    len value exceeding 2GB.
 239
 240    lo_truncate is new as of PostgreSQL 8.3; if this function is run
 241    against an older server version, it will fail and return -1.
 242
 243    lo_truncate64 is new as of PostgreSQL 9.3; if this function is run
 244    against an older server version, it will fail and return -1.
 245
 246 33.3.10. Closing a Large Object Descriptor #
 247
 248    A large object descriptor can be closed by calling
 249 int lo_close(PGconn *conn, int fd);
 250
 251    where fd is a large object descriptor returned by lo_open. On success,
 252    lo_close returns zero. On error, the return value is -1.
 253
 254    Any large object descriptors that remain open at the end of a
 255    transaction will be closed automatically.
 256
 257 33.3.11. Removing a Large Object #
 258
 259    To remove a large object from the database, call
 260 int lo_unlink(PGconn *conn, Oid lobjId);
 261
 262    The lobjId argument specifies the OID of the large object to remove.
 263    Returns 1 if successful, -1 on failure.