GSeekable: GIO Reference Manual

## GSeekable GSeekable — Stream seeking interface |

## Functions

goffset | g_seekable_tell ()
gboolean | g_seekable_can_seek ()
gboolean | g_seekable_seek ()
gboolean | g_seekable_can_truncate ()
gboolean | g_seekable_truncate ()

## Types and Values

| GSeekable
struct | GSeekableIface

## Object Hierarchy

        GInterface
        ╰── GSeekable

## Prerequisites

GSeekable requires GObject.

## Known Implementations

GSeekable is implemented by GBufferedInputStream, GBufferedOutputStream, GDataInputStream, GDataOutputStream, GFileIOStream, GFileInputStream, GFileOutputStream, GMemoryInputStream and GMemoryOutputStream.

## Includes

    #include <gio/gio.h>

## Description

GSeekable is implemented by streams (implementations of GInputStream or GOutputStream) that support seeking.

Seekable streams largely fall into two categories: resizable and fixed-size.

GSeekable on fixed-sized streams is approximately the same as POSIX `lseek()` on a block device (for example: attmepting to seek past the end of the device is an error). Fixed streams typically cannot be truncated.

GSeekable on resizable streams is approximately the same as POSIX `lseek()` on a normal file. Seeking past the end and writing data will usually cause the stream to resize by introducing zero bytes.

## Functions

### g_seekable_tell ()

    goffset
    g_seekable_tell (GSeekable *seekable);

Tells the current position within the stream.

#### Parameters

seekable | a GSeekable. |

#### Returns

the offset from the beginning of the buffer.

### g_seekable_can_seek ()

    gboolean
    g_seekable_can_seek (GSeekable *seekable);

Tests if the stream supports the GSeekableIface.

#### Parameters

seekable | a GSeekable. |

#### Returns

`TRUE` if `seekable` can be seeked. `FALSE` otherwise.

### g_seekable_seek ()

    gboolean
    g_seekable_seek (GSeekable *seekable,
                     goffset offset,
                     GSeekType type,
                     GCancellable *cancellable,
                     GError **error);

Seeks in the stream by the given `offset` , modified by `type` .

Attempting to seek past the end of the stream will have different results depending on if the stream is fixed-sized or resizable. If the stream is resizable then seeking past the end and then writing will result in zeros filling the empty space. Seeking past the end of a resizable stream and reading will result in EOF. Seeking past the end of a fixed-sized stream will fail.

Any operation that would result in a negative offset will fail.

If `cancellable` is not `NULL`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be returned.

#### Parameters

seekable | a GSeekable. |
offset | a goffset. |
type | a GSeekType. |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

`TRUE` if successful. If an error has occurred, this function will return `FALSE` and set `error` appropriately if present.

### g_seekable_can_truncate ()

    gboolean
    g_seekable_can_truncate (GSeekable *seekable);

Tests if the length of the stream can be adjusted with `g_seekable_truncate()`.

#### Parameters

seekable | a GSeekable. |

#### Returns

`TRUE` if the stream can be truncated, `FALSE` otherwise.

### g_seekable_truncate ()

    gboolean
    g_seekable_truncate (GSeekable *seekable,
                         goffset offset,
                         GCancellable *cancellable,
                         GError **error);

Sets the length of the stream to `offset` . If the stream was previously larger than `offset` , the extra data is discarded. If the stream was previouly shorter than `offset` , it is extended with NUL ('\0') bytes.

If `cancellable` is not `NULL`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error.

[virtual truncate_fn]

#### Parameters

seekable | a GSeekable. |
offset | new length for `seekable` , in bytes. |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

`TRUE` if successful. If an error has occurred, this function will return `FALSE` and set `error` appropriately if present.

## Types and Values

### GSeekable

    typedef struct _GSeekable GSeekable;

Seek object for streaming operations.

### struct GSeekableIface

    struct GSeekableIface {
      GTypeInterface g_iface;

      /* Virtual Table */

      goffset     (* tell)	         (GSeekable    *seekable);

      gboolean    (* can_seek)       (GSeekable    *seekable);
      gboolean    (* seek)	         (GSeekable    *seekable,
    				  goffset       offset,
    				  GSeekType     type,
    				  GCancellable *cancellable,
    				  GError      **error);

      gboolean    (* can_truncate)   (GSeekable    *seekable);
      gboolean    (* truncate_fn)    (GSeekable    *seekable,
    				  goffset       offset,
    				  GCancellable *cancellable,
    				  GError       **error);

      /* TODO: Async seek/truncate */
    };

Provides an interface for implementing seekable functionality on I/O Streams.

#### Members

`tell` () | Tells the current location within a stream. |
`can_seek` () | Checks if seeking is supported by the stream. |
`seek` () | Seeks to a location within a stream. |
`can_truncate` () | Checks if truncation is supported by the stream. |
`truncate_fn` () | Truncates a stream. |

## See Also

GInputStream, GOutputStream