69
69
access reads and writes.
70
70
</para>
71
71
72
+ <para>
73
+ The chunks stored for a large object do not have to be contiguous.
74
+ For example, if an application opens a new large object, seeks to offset
75
+ 1000000, and writes a few bytes there, this does not result in allocation
76
+ of 1000000 bytes worth of storage; only of chunks covering the range of
77
+ data bytes actually written. A read operation will, however, read out
78
+ zeroes for any unallocated locations preceding the last existing chunk.
79
+ This corresponds to the common behavior of <quote>sparsely allocated</>
80
+ files in <acronym>Unix</acronym> file systems.
81
+ </para>
82
+
72
83
<para>
73
84
As of <productname>PostgreSQL</> 9.0, large objects have an owner
74
85
and a set of access permissions, which can be managed using
@@ -299,11 +310,19 @@ inv_fd = lo_open(conn, inv_oid, INV_READ|INV_WRITE);
299
310
int lo_write(PGconn *conn, int fd, const char *buf, size_t len);
300
311
</synopsis>
301
312
writes <parameter>len</parameter> bytes from <parameter>buf</parameter>
302
- to large object descriptor <parameter>fd</>. The <parameter>fd</parameter>
303
- argument must have been returned by a previous
304
- <function>lo_open</function>. The number of bytes actually
305
- written is returned. In the event of an error, the return value
306
- is -1.
313
+ (which must be of size <parameter>len</parameter>) to large object
314
+ descriptor <parameter>fd</>. The <parameter>fd</parameter> argument must
315
+ have been returned by a previous <function>lo_open</function>. The
316
+ number of bytes actually written is returned (in the current
317
+ implementation, this will always equal <parameter>len</parameter> unless
318
+ there is an error). In the event of an error, the return value is -1.
319
+ </para>
320
+
321
+ <para>
322
+ Although the <parameter>len</parameter> parameter is declared as
323
+ <type>size_t</>, this function will reject length values larger than
324
+ <literal>INT_MAX</>. In practice, it's best to transfer data in chunks
325
+ of at most a few megabytes anyway.
307
326
</para>
308
327
</sect2>
309
328
@@ -316,13 +335,22 @@ int lo_write(PGconn *conn, int fd, const char *buf, size_t len);
316
335
<synopsis>
317
336
int lo_read(PGconn *conn, int fd, char *buf, size_t len);
318
337
</synopsis>
319
- reads <parameter>len</parameter> bytes from large object descriptor
320
- <parameter>fd</parameter> into <parameter>buf</parameter>. The
321
- <parameter>fd</parameter> argument must have been returned by a
322
- previous <function>lo_open</function>. The number of bytes
323
- actually read is returned. In the event of an error, the return
338
+ reads up to <parameter>len</parameter> bytes from large object descriptor
339
+ <parameter>fd</parameter> into <parameter>buf</parameter> (which must be
340
+ of size <parameter>len</parameter>). The <parameter>fd</parameter>
341
+ argument must have been returned by a previous
342
+ <function>lo_open</function>. The number of bytes actually read is
343
+ returned; this will be less than <parameter>len</parameter> if the end of
344
+ the large object is reached first. In the event of an error, the return
324
345
value is -1.
325
346
</para>
347
+
348
+ <para>
349
+ Although the <parameter>len</parameter> parameter is declared as
350
+ <type>size_t</>, this function will reject length values larger than
351
+ <literal>INT_MAX</>. In practice, it's best to transfer data in chunks
352
+ of at most a few megabytes anyway.
353
+ </para>
326
354
</sect2>
327
355
328
356
<sect2 id="lo-seek">
@@ -416,7 +444,7 @@ int lo_truncate(PGcon *conn, int fd, size_t len);
416
444
<parameter>fd</parameter> argument must have been returned by a
417
445
previous <function>lo_open</function>. If <parameter>len</> is
418
446
greater than the large object's current length, the large object
419
- is extended with null bytes ('\0').
447
+ is extended to the specified length with null bytes ('\0').
420
448
On success, <function>lo_truncate</function> returns
421
449
zero. On error, the return value is -1.
422
450
</para>
@@ -426,6 +454,12 @@ int lo_truncate(PGcon *conn, int fd, size_t len);
426
454
<parameter>fd</parameter> is not changed.
427
455
</para>
428
456
457
+ <para>
458
+ Although the <parameter>len</parameter> parameter is declared as
459
+ <type>size_t</>, <function>lo_truncate</function> will reject length
460
+ values larger than <literal>INT_MAX</>.
461
+ </para>
462
+
429
463
<para>
430
464
<indexterm><primary>lo_truncate64</></>
431
465
When dealing with large objects that might exceed 2GB in size,
0 commit comments