GBufferedInputStream: GIO Reference Manual

## GBufferedInputStream GBufferedInputStream — Buffered Input Stream |

## Functions

GInputStream * | g_buffered_input_stream_new ()
GInputStream * | g_buffered_input_stream_new_sized ()
gsize | g_buffered_input_stream_get_buffer_size ()
void | g_buffered_input_stream_set_buffer_size ()
gsize | g_buffered_input_stream_get_available ()
const void * | g_buffered_input_stream_peek_buffer ()
gsize | g_buffered_input_stream_peek ()
gssize | g_buffered_input_stream_fill ()
void | g_buffered_input_stream_fill_async ()
gssize | g_buffered_input_stream_fill_finish ()
int | g_buffered_input_stream_read_byte ()

## Properties

guint | buffer-size | Read / Write / Construct

## Types and Values

| GBufferedInputStream

## Object Hierarchy

        GObject
        ╰── GInputStream
            ╰── GFilterInputStream
                ╰── GBufferedInputStream
                    ╰── GDataInputStream

## Implemented Interfaces

GBufferedInputStream implements GSeekable.

## Includes

    #include <gio/gio.h>

## Description

Buffered input stream implements GFilterInputStream and provides for buffered reads.

By default, GBufferedInputStream's buffer size is set at 4 kilobytes.

To create a buffered input stream, use `g_buffered_input_stream_new()`, or `g_buffered_input_stream_new_sized()` to specify the buffer's size at construction.

To get the size of a buffer within a buffered input stream, use `g_buffered_input_stream_get_buffer_size()`. To change the size of a buffered input stream's buffer, use `g_buffered_input_stream_set_buffer_size()`. Note that the buffer's size cannot be reduced below the size of the data within the buffer.

## Functions

### g_buffered_input_stream_new ()

    GInputStream *
    g_buffered_input_stream_new (GInputStream *base_stream);

Creates a new GInputStream from the given `base_stream` , with a buffer set to the default size (4 kilobytes).

#### Parameters

base_stream | a GInputStream |

#### Returns

a GInputStream for the given `base_stream` .

### g_buffered_input_stream_new_sized ()

    GInputStream *
    g_buffered_input_stream_new_sized (GInputStream *base_stream,
                                       gsize size);

Creates a new GBufferedInputStream from the given `base_stream` , with a buffer set to `size` .

#### Parameters

base_stream | a GInputStream |
size | a gsize |

#### Returns

a GInputStream.

### g_buffered_input_stream_get_buffer_size ()

    gsize
    g_buffered_input_stream_get_buffer_size
                                   (GBufferedInputStream *stream);

Gets the size of the input buffer.

#### Parameters

stream | a GBufferedInputStream |

#### Returns

the current buffer size.

### g_buffered_input_stream_set_buffer_size ()

    void
    g_buffered_input_stream_set_buffer_size
                                   (GBufferedInputStream *stream,
                                    gsize size);

Sets the size of the internal buffer of `stream` to `size` , or to the size of the contents of the buffer. The buffer can never be resized smaller than its current contents.

#### Parameters

stream | a GBufferedInputStream |
size | a gsize |

### g_buffered_input_stream_get_available ()

    gsize
    g_buffered_input_stream_get_available (GBufferedInputStream *stream);

Gets the size of the available data within the stream.

#### Parameters

stream | GBufferedInputStream |

#### Returns

size of the available stream.

### g_buffered_input_stream_peek_buffer ()

    const void *
    g_buffered_input_stream_peek_buffer (GBufferedInputStream *stream,
                                         gsize *count);

Returns the buffer with the currently available bytes. The returned buffer must not be modified and will become invalid when reading from the stream or filling the buffer.

#### Parameters

stream | a GBufferedInputStream |
count | a gsize to get the number of bytes available in the buffer. | [out]

#### Returns

read-only buffer.

[array length=count][element-type guint8][transfer none]

### g_buffered_input_stream_peek ()

    gsize
    g_buffered_input_stream_peek (GBufferedInputStream *stream,
                                  void *buffer,
                                  gsize offset,
                                  gsize count);

Peeks in the buffer, copying data of size `count` into `buffer` , offset `offset` bytes.

#### Parameters

stream | a GBufferedInputStream |
buffer | a pointer to an allocated chunk of memory. | [array length=count][element-type guint8]
offset | a gsize |
count | a gsize |

#### Returns

a gsize of the number of bytes peeked, or -1 on error.

### g_buffered_input_stream_fill ()

    gssize
    g_buffered_input_stream_fill (GBufferedInputStream *stream,
                                  gssize count,
                                  GCancellable *cancellable,
                                  GError **error);

Tries to read `count` bytes from the stream into the buffer. Will block during this read.

If `count` is zero, returns zero and does nothing. A value of `count` larger than `G_MAXSSIZE` will cause a `G_IO_ERROR_INVALID_ARGUMENT` error.

On success, the number of bytes read into the buffer is returned. It is not an error if this is not the same as the requested size, as it can happen e.g. near the end of a file. Zero is returned on end of file (or if `count` is zero), but never otherwise.

If `count` is -1 then the attempted read size is equal to the number of bytes that are required to fill the buffer.

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.

On error -1 is returned and `error` is set accordingly.

For the asynchronous, non-blocking, version of this function, see `g_buffered_input_stream_fill_async()`.

#### Parameters

stream | a GBufferedInputStream |
count | the number of bytes that will be read from the stream |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | location to store the error occurring, or `NULL` to ignore |

#### Returns

the number of bytes read into `stream` 's buffer, up to `count` , or -1 on error.

### g_buffered_input_stream_fill_async ()

    void
    g_buffered_input_stream_fill_async (GBufferedInputStream *stream,
                                        gssize count,
                                        int io_priority,
                                        GCancellable *cancellable,
                                        GAsyncReadyCallback callback,
                                        gpointer user_data);

Reads data into `stream` 's buffer asynchronously, up to `count` size. `io_priority` can be used to prioritize reads. For the synchronous version of this function, see `g_buffered_input_stream_fill()`.

If `count` is -1 then the attempted read size is equal to the number of bytes that are required to fill the buffer.

#### Parameters

stream | a GBufferedInputStream |
count | the number of bytes that will be read from the stream |
io_priority | the I/O priority of the request |
cancellable | optional GCancellable object. | [nullable]
callback | a GAsyncReadyCallback. | [scope async]
user_data | a gpointer. | [closure]

### g_buffered_input_stream_fill_finish ()

    gssize
    g_buffered_input_stream_fill_finish (GBufferedInputStream *stream,
                                         GAsyncResult *result,
                                         GError **error);

Finishes an asynchronous read.

#### Parameters

stream | a GBufferedInputStream |
result | a GAsyncResult |
error | a GError |

#### Returns

a gssize of the read stream, or `-1` on an error.

### g_buffered_input_stream_read_byte ()

    int
    g_buffered_input_stream_read_byte (GBufferedInputStream *stream,
                                       GCancellable *cancellable,
                                       GError **error);

Tries to read a single byte from the stream or the buffer. Will block during this read.

On success, the byte read from the stream is returned. On end of stream -1 is returned but it's not an exceptional error and `error` is not set.

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.

On error -1 is returned and `error` is set accordingly.

#### Parameters

stream | a GBufferedInputStream |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | location to store the error occurring, or `NULL` to ignore |

#### Returns

the byte read from the `stream` , or -1 on end of stream or error.

## Types and Values

### GBufferedInputStream

    typedef struct _GBufferedInputStream GBufferedInputStream;

Implements GFilterInputStream with a sized input buffer.

## Property Details

### The `“buffer-size”` property

      “buffer-size”              guint

The size of the backend buffer.

Owner: GBufferedInputStream

Flags: Read / Write / Construct

Allowed values: >= 1

Default value: 4096

## See Also

GFilterInputStream, GInputStream