GMemoryOutputStream: GIO Reference Manual

## GMemoryOutputStream GMemoryOutputStream — Streaming output operations on memory chunks |

## Functions

gpointer | (*GReallocFunc) ()
GOutputStream * | g_memory_output_stream_new ()
GOutputStream * | g_memory_output_stream_new_resizable ()
gpointer | g_memory_output_stream_get_data ()
gsize | g_memory_output_stream_get_size ()
gsize | g_memory_output_stream_get_data_size ()
gpointer | g_memory_output_stream_steal_data ()
GBytes * | g_memory_output_stream_steal_as_bytes ()

## Properties

gpointer | data | Read / Write / Construct Only
gulong | data-size | Read
gpointer | destroy-function | Read / Write / Construct Only
gpointer | realloc-function | Read / Write / Construct Only
gulong | size | Read / Write / Construct Only

## Types and Values

| GMemoryOutputStream

## Object Hierarchy

        GObject
        ╰── GOutputStream
            ╰── GMemoryOutputStream

## Implemented Interfaces

GMemoryOutputStream implements GSeekable and GPollableOutputStream.

## Includes

    #include <gio/gio.h>

## Description

GMemoryOutputStream is a class for using arbitrary memory chunks as output for GIO streaming output operations.

As of GLib 2.34, GMemoryOutputStream trivially implements GPollableOutputStream: it always polls as ready.

## Functions

### GReallocFunc ()

    gpointer
    (*GReallocFunc) (gpointer data,
                     gsize size);

Changes the size of the memory block pointed to by `data` to `size` bytes.

The function should have the same semantics as `realloc()`.

#### Parameters

data | memory block to reallocate |
size | size to reallocate `data` to |

#### Returns

a pointer to the reallocated memory

### g_memory_output_stream_new ()

    GOutputStream *
    g_memory_output_stream_new (gpointer data,
                                gsize size,
                                GReallocFunc realloc_function,
                                GDestroyNotify destroy_function);

Creates a new GMemoryOutputStream.

In most cases this is not the function you want. See `g_memory_output_stream_new_resizable()` instead.

If `data` is non-`NULL`, the stream will use that for its internal storage.

If `realloc_fn` is non-`NULL`, it will be used for resizing the internal storage when necessary and the stream will be considered resizable. In that case, the stream will start out being (conceptually) empty. `size` is used only as a hint for how big `data` is. Specifically, seeking to the end of a newly-created stream will seek to zero, not `size` . Seeking past the end of the stream and then writing will introduce a zero-filled gap.

If `realloc_fn` is `NULL` then the stream is fixed-sized. Seeking to the end will seek to `size` exactly. Writing past the end will give an 'out of space' error. Attempting to seek past the end will fail. Unlike the resizable case, seeking to an offset within the stream and writing will preserve the bytes passed in as `data` before that point and will return them as part of `g_memory_output_stream_steal_data()`. If you intend to seek you should probably therefore ensure that `data` is properly initialised.

It is probably only meaningful to provide `data` and `size` in the case that you want a fixed-sized stream. Put another way: if `realloc_fn` is non-`NULL` then it makes most sense to give `data` as `NULL` and `size` as 0 (allowing GMemoryOutputStream to do the initial allocation for itself).

    1
    2
    3
    4
    5
    6
    7
    8
    9
    // a stream that can grow
    stream = g_memory_output_stream_new (NULL, 0, realloc, free);

    // another stream that can grow
    stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free);

    // a fixed-size stream
    data = malloc (200);
    stream3 = g_memory_output_stream_new (data, 200, NULL, free);

[skip]

#### Parameters

data | pointer to a chunk of memory to use, or `NULL`. | [allow-none]
size | the size of `data` |
realloc_function | a function with `realloc()` semantics (like `g_realloc()`) to be called when `data` needs to be grown, or `NULL`. | [allow-none]
destroy_function | a function to be called on `data` when the stream is finalized, or `NULL`. | [allow-none]

#### Returns

A newly created GMemoryOutputStream object.

### g_memory_output_stream_new_resizable ()

    GOutputStream *
    g_memory_output_stream_new_resizable (void);

Creates a new GMemoryOutputStream, using `g_realloc()` and `g_free()` for memory allocation.

Since: 2.36

### g_memory_output_stream_get_data ()

    gpointer
    g_memory_output_stream_get_data (GMemoryOutputStream *ostream);

Gets any loaded data from the `ostream` .

Note that the returned pointer may become invalid on the next write or truncate operation on the stream.

#### Parameters

ostream | a GMemoryOutputStream |

#### Returns

pointer to the stream's data, or `NULL` if the data has been stolen.

[transfer none]

### g_memory_output_stream_get_size ()

    gsize
    g_memory_output_stream_get_size (GMemoryOutputStream *ostream);

Gets the size of the currently allocated data area (available from `g_memory_output_stream_get_data()`).

You probably don't want to use this function on resizable streams. See `g_memory_output_stream_get_data_size()` instead. For resizable streams the size returned by this function is an implementation detail and may be change at any time in response to operations on the stream.

If the stream is fixed-sized (ie: no realloc was passed to `g_memory_output_stream_new()`) then this is the maximum size of the stream and further writes will return `G_IO_ERROR_NO_SPACE`.

In any case, if you want the number of bytes currently written to the stream, use `g_memory_output_stream_get_data_size()`.

#### Parameters

ostream | a GMemoryOutputStream |

#### Returns

the number of bytes allocated for the data buffer

### g_memory_output_stream_get_data_size ()

    gsize
    g_memory_output_stream_get_data_size (GMemoryOutputStream *ostream);

Returns the number of bytes from the start up to including the last byte written in the stream that has not been truncated away.

#### Parameters

ostream | a GMemoryOutputStream |

#### Returns

the number of bytes written to the stream

Since: 2.18

### g_memory_output_stream_steal_data ()

    gpointer
    g_memory_output_stream_steal_data (GMemoryOutputStream *ostream);

Gets any loaded data from the `ostream` . Ownership of the data is transferred to the caller; when no longer needed it must be freed using the free function set in `ostream` 's “destroy-function” property.

`ostream` must be closed before calling this function.

#### Parameters

ostream | a GMemoryOutputStream |

#### Returns

the stream's data, or `NULL` if it has previously been stolen.

[transfer full]

Since: 2.26

### g_memory_output_stream_steal_as_bytes ()

    GBytes *
    g_memory_output_stream_steal_as_bytes (GMemoryOutputStream *ostream);

Returns data from the `ostream` as a GBytes. `ostream` must be closed before calling this function.

#### Parameters

ostream | a GMemoryOutputStream |

#### Returns

the stream's data.

[transfer full]

Since: 2.34

## Types and Values

### GMemoryOutputStream

    typedef struct _GMemoryOutputStream GMemoryOutputStream;

Implements GOutputStream for arbitrary memory chunks.

## Property Details

### The `“data”` property

      “data”                     gpointer

Pointer to buffer where data will be written.

Flags: Read / Write / Construct Only

Since: 2.24

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

      “data-size”                gulong

Size of data written to the buffer.

Flags: Read

Since: 2.24

### The `“destroy-function”` property

      “destroy-function”         gpointer

Function called with the buffer as argument when the stream is destroyed.

[skip]

Flags: Read / Write / Construct Only

Since: 2.24

### The `“realloc-function”` property

      “realloc-function”         gpointer

Function with realloc semantics called to enlarge the buffer.

[skip]

Flags: Read / Write / Construct Only

Since: 2.24

### The `“size”` property

      “size”                     gulong

Current size of the data buffer.

Flags: Read / Write / Construct Only

Since: 2.24

## See Also

GMemoryInputStream