GDataInputStream: GIO Reference Manual

## GDataInputStream GDataInputStream — Data Input Stream |

## Functions

GDataInputStream * | g_data_input_stream_new ()
void | g_data_input_stream_set_byte_order ()
GDataStreamByteOrder | g_data_input_stream_get_byte_order ()
void | g_data_input_stream_set_newline_type ()
GDataStreamNewlineType | g_data_input_stream_get_newline_type ()
guchar | g_data_input_stream_read_byte ()
gint16 | g_data_input_stream_read_int16 ()
guint16 | g_data_input_stream_read_uint16 ()
gint32 | g_data_input_stream_read_int32 ()
guint32 | g_data_input_stream_read_uint32 ()
gint64 | g_data_input_stream_read_int64 ()
guint64 | g_data_input_stream_read_uint64 ()
char * | g_data_input_stream_read_line ()
char * | g_data_input_stream_read_line_utf8 ()
void | g_data_input_stream_read_line_async ()
char * | g_data_input_stream_read_line_finish ()
char * | g_data_input_stream_read_line_finish_utf8 ()
char * | g_data_input_stream_read_upto ()
void | g_data_input_stream_read_upto_async ()
char * | g_data_input_stream_read_upto_finish ()
char * | g_data_input_stream_read_until ()
void | g_data_input_stream_read_until_async ()
char * | g_data_input_stream_read_until_finish ()

## Properties

GDataStreamByteOrder | byte-order | Read / Write
GDataStreamNewlineType | newline-type | Read / Write

## Types and Values

| GDataInputStream
enum | GDataStreamByteOrder
enum | GDataStreamNewlineType

## Object Hierarchy

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

## Implemented Interfaces

GDataInputStream implements GSeekable.

## Includes

    #include <gio/gio.h>

## Description

Data input stream implements GInputStream and includes functions for reading structured data directly from a binary input stream.

## Functions

### g_data_input_stream_new ()

    GDataInputStream *
    g_data_input_stream_new (GInputStream *base_stream);

Creates a new data input stream for the `base_stream` .

#### Parameters

base_stream | a GInputStream. |

#### Returns

a new GDataInputStream.

### g_data_input_stream_set_byte_order ()

    void
    g_data_input_stream_set_byte_order (GDataInputStream *stream,
                                        GDataStreamByteOrder order);

This function sets the byte order for the given `stream` . All subsequent reads from the `stream` will be read in the given `order` .

#### Parameters

stream | a given GDataInputStream. |
order | a GDataStreamByteOrder to set. |

### g_data_input_stream_get_byte_order ()

    GDataStreamByteOrder
    g_data_input_stream_get_byte_order (GDataInputStream *stream);

Gets the byte order for the data input stream.

#### Parameters

stream | a given GDataInputStream. |

#### Returns

the `stream` 's current GDataStreamByteOrder.

### g_data_input_stream_set_newline_type ()

    void
    g_data_input_stream_set_newline_type (GDataInputStream *stream,
                                          GDataStreamNewlineType type);

Sets the newline type for the `stream` .

Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read chunk ends in "CR" we must read an additional byte to know if this is "CR" or "CR LF", and this might block if there is no more data available.

#### Parameters

stream | a GDataInputStream. |
type | the type of new line return as GDataStreamNewlineType. |

### g_data_input_stream_get_newline_type ()

    GDataStreamNewlineType
    g_data_input_stream_get_newline_type (GDataInputStream *stream);

Gets the current newline type for the `stream` .

#### Parameters

stream | a given GDataInputStream. |

#### Returns

GDataStreamNewlineType for the given `stream` .

### g_data_input_stream_read_byte ()

    guchar
    g_data_input_stream_read_byte (GDataInputStream *stream,
                                   GCancellable *cancellable,
                                   GError **error);

Reads an unsigned 8-bit/1-byte value from `stream` .

#### Parameters

stream | a given GDataInputStream. |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | GError for error reporting. |

#### Returns

an unsigned 8-bit/1-byte value read from the `stream` or `0` if an error occurred.

### g_data_input_stream_read_int16 ()

    gint16
    g_data_input_stream_read_int16 (GDataInputStream *stream,
                                    GCancellable *cancellable,
                                    GError **error);

Reads a 16-bit/2-byte value from `stream` .

In order to get the correct byte order for this read operation, see `g_data_input_stream_get_byte_order()` and `g_data_input_stream_set_byte_order()`.

#### Parameters

stream | a given GDataInputStream. |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | GError for error reporting. |

#### Returns

a signed 16-bit/2-byte value read from `stream` or `0` if an error occurred.

### g_data_input_stream_read_uint16 ()

    guint16
    g_data_input_stream_read_uint16 (GDataInputStream *stream,
                                     GCancellable *cancellable,
                                     GError **error);

Reads an unsigned 16-bit/2-byte value from `stream` .

In order to get the correct byte order for this read operation, see `g_data_input_stream_get_byte_order()` and `g_data_input_stream_set_byte_order()`.

#### Parameters

stream | a given GDataInputStream. |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | GError for error reporting. |

#### Returns

an unsigned 16-bit/2-byte value read from the `stream` or `0` if an error occurred.

### g_data_input_stream_read_int32 ()

    gint32
    g_data_input_stream_read_int32 (GDataInputStream *stream,
                                    GCancellable *cancellable,
                                    GError **error);

Reads a signed 32-bit/4-byte value from `stream` .

In order to get the correct byte order for this read operation, see `g_data_input_stream_get_byte_order()` and `g_data_input_stream_set_byte_order()`.

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

stream | a given GDataInputStream. |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | GError for error reporting. |

#### Returns

a signed 32-bit/4-byte value read from the `stream` or `0` if an error occurred.

### g_data_input_stream_read_uint32 ()

    guint32
    g_data_input_stream_read_uint32 (GDataInputStream *stream,
                                     GCancellable *cancellable,
                                     GError **error);

Reads an unsigned 32-bit/4-byte value from `stream` .

In order to get the correct byte order for this read operation, see `g_data_input_stream_get_byte_order()` and `g_data_input_stream_set_byte_order()`.

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

stream | a given GDataInputStream. |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | GError for error reporting. |

#### Returns

an unsigned 32-bit/4-byte value read from the `stream` or `0` if an error occurred.

### g_data_input_stream_read_int64 ()

    gint64
    g_data_input_stream_read_int64 (GDataInputStream *stream,
                                    GCancellable *cancellable,
                                    GError **error);

Reads a 64-bit/8-byte value from `stream` .

In order to get the correct byte order for this read operation, see `g_data_input_stream_get_byte_order()` and `g_data_input_stream_set_byte_order()`.

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

stream | a given GDataInputStream. |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | GError for error reporting. |

#### Returns

a signed 64-bit/8-byte value read from `stream` or `0` if an error occurred.

### g_data_input_stream_read_uint64 ()

    guint64
    g_data_input_stream_read_uint64 (GDataInputStream *stream,
                                     GCancellable *cancellable,
                                     GError **error);

Reads an unsigned 64-bit/8-byte value from `stream` .

In order to get the correct byte order for this read operation, see `g_data_input_stream_get_byte_order()`.

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

stream | a given GDataInputStream. |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | GError for error reporting. |

#### Returns

an unsigned 64-bit/8-byte read from `stream` or `0` if an error occurred.

### g_data_input_stream_read_line ()

    char *
    g_data_input_stream_read_line (GDataInputStream *stream,
                                   gsize *length,
                                   GCancellable *cancellable,
                                   GError **error);

Reads a line from the data input stream. Note that no encoding checks or conversion is performed; the input is not guaranteed to be UTF-8, and may in fact have embedded NUL characters.

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

stream | a given GDataInputStream. |
length | a gsize to get the length of the data read in. | [out]
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | GError for error reporting. |

#### Returns

a NUL terminated byte array with the line that was read in (without the newlines). Set `length` to a gsize to get the length of the read line. On an error, it will return `NULL` and `error` will be set. If there's no content to read, it will still return `NULL`, but `error` won't be set.

[nullable][transfer full][array zero-terminated=1][element-type guint8]

### g_data_input_stream_read_line_utf8 ()

    char *
    g_data_input_stream_read_line_utf8 (GDataInputStream *stream,
                                        gsize *length,
                                        GCancellable *cancellable,
                                        GError **error);

Reads a UTF-8 encoded line from the data input stream.

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

stream | a given GDataInputStream. |
length | a gsize to get the length of the data read in. | [out]
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | GError for error reporting. |

#### Returns

a NUL terminated UTF-8 string with the line that was read in (without the newlines). Set `length` to a gsize to get the length of the read line. On an error, it will return `NULL` and `error` will be set. For UTF-8 conversion errors, the set error domain is `G_CONVERT_ERROR`. If there's no content to read, it will still return `NULL`, but `error` won't be set.

[nullable][transfer full]

Since: 2.30

### g_data_input_stream_read_line_async ()

    void
    g_data_input_stream_read_line_async (GDataInputStream *stream,
                                         gint io_priority,
                                         GCancellable *cancellable,
                                         GAsyncReadyCallback callback,
                                         gpointer user_data);

The asynchronous version of `g_data_input_stream_read_line()`. It is an error to have two outstanding calls to this function.

When the operation is finished, `callback` will be called. You can then call `g_data_input_stream_read_line_finish()` to get the result of the operation.

#### Parameters

stream | a given GDataInputStream. |
io_priority | the I/O priority of the request |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
callback | callback to call when the request is satisfied. | [scope async]
user_data | the data to pass to callback function. | [closure]

Since: 2.20

### g_data_input_stream_read_line_finish ()

    char *
    g_data_input_stream_read_line_finish (GDataInputStream *stream,
                                          GAsyncResult *result,
                                          gsize *length,
                                          GError **error);

Finish an asynchronous call started by `g_data_input_stream_read_line_async()`. Note the warning about string encoding in `g_data_input_stream_read_line()` applies here as well.

#### Parameters

stream | a given GDataInputStream. |
result | the GAsyncResult that was provided to the callback. |
length | a gsize to get the length of the data read in. | [out]
error | GError for error reporting. |

#### Returns

a NUL-terminated byte array with the line that was read in (without the newlines). Set `length` to a gsize to get the length of the read line. On an error, it will return `NULL` and `error` will be set. If there's no content to read, it will still return `NULL`, but `error` won't be set.

[nullable][transfer full][array zero-terminated=1][element-type guint8]

Since: 2.20

### g_data_input_stream_read_line_finish_utf8 ()

    char *
    g_data_input_stream_read_line_finish_utf8
                                   (GDataInputStream *stream,
                                    GAsyncResult *result,
                                    gsize *length,
                                    GError **error);

Finish an asynchronous call started by `g_data_input_stream_read_line_async()`.

#### Parameters

stream | a given GDataInputStream. |
result | the GAsyncResult that was provided to the callback. |
length | a gsize to get the length of the data read in. | [out]
error | GError for error reporting. |

#### Returns

a string with the line that was read in (without the newlines). Set `length` to a gsize to get the length of the read line. On an error, it will return `NULL` and `error` will be set. For UTF-8 conversion errors, the set error domain is `G_CONVERT_ERROR`. If there's no content to read, it will still return `NULL`, but `error` won't be set.

[nullable][transfer full]

Since: 2.30

### g_data_input_stream_read_upto ()

    char *
    g_data_input_stream_read_upto (GDataInputStream *stream,
                                   const gchar *stop_chars,
                                   gssize stop_chars_len,
                                   gsize *length,
                                   GCancellable *cancellable,
                                   GError **error);

Reads a string from the data input stream, up to the first occurrence of any of the stop characters.

In contrast to `g_data_input_stream_read_until()`, this function does not consume the stop character. You have to use `g_data_input_stream_read_byte()` to get it before calling `g_data_input_stream_read_upto()` again.

Note that `stop_chars` may contain '\0' if `stop_chars_len` is specified.

#### Parameters

stream | a GDataInputStream |
stop_chars | characters to terminate the read |
stop_chars_len | length of `stop_chars` . May be -1 if `stop_chars` is nul-terminated |
length | a gsize to get the length of the data read in. | [out]
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | GError for error reporting |

#### Returns

a string with the data that was read before encountering any of the stop characters. Set `length` to a gsize to get the length of the string. This function will return `NULL` on an error.

[transfer full]

Since: 2.26

### g_data_input_stream_read_upto_async ()

    void
    g_data_input_stream_read_upto_async (GDataInputStream *stream,
                                         const gchar *stop_chars,
                                         gssize stop_chars_len,
                                         gint io_priority,
                                         GCancellable *cancellable,
                                         GAsyncReadyCallback callback,
                                         gpointer user_data);

The asynchronous version of `g_data_input_stream_read_upto()`. It is an error to have two outstanding calls to this function.

In contrast to `g_data_input_stream_read_until()`, this function does not consume the stop character. You have to use `g_data_input_stream_read_byte()` to get it before calling `g_data_input_stream_read_upto()` again.

Note that `stop_chars` may contain '\0' if `stop_chars_len` is specified.

When the operation is finished, `callback` will be called. You can then call `g_data_input_stream_read_upto_finish()` to get the result of the operation.

#### Parameters

stream | a GDataInputStream |
stop_chars | characters to terminate the read |
stop_chars_len | length of `stop_chars` . May be -1 if `stop_chars` is nul-terminated |
io_priority | the I/O priority of the request |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
callback | callback to call when the request is satisfied. | [scope async]
user_data | the data to pass to callback function. | [closure]

Since: 2.26

### g_data_input_stream_read_upto_finish ()

    char *
    g_data_input_stream_read_upto_finish (GDataInputStream *stream,
                                          GAsyncResult *result,
                                          gsize *length,
                                          GError **error);

Finish an asynchronous call started by `g_data_input_stream_read_upto_async()`.

Note that this function does not consume the stop character. You have to use `g_data_input_stream_read_byte()` to get it before calling `g_data_input_stream_read_upto_async()` again.

#### Parameters

stream | a GDataInputStream |
result | the GAsyncResult that was provided to the callback |
length | a gsize to get the length of the data read in. | [out]
error | GError for error reporting |

#### Returns

a string with the data that was read before encountering any of the stop characters. Set `length` to a gsize to get the length of the string. This function will return `NULL` on an error.

[transfer full]

Since: 2.24

### g_data_input_stream_read_until ()

    char *
    g_data_input_stream_read_until (GDataInputStream *stream,
                                    const gchar *stop_chars,
                                    gsize *length,
                                    GCancellable *cancellable,
                                    GError **error);

Reads a string from the data input stream, up to the first occurrence of any of the stop characters.

Note that, in contrast to `g_data_input_stream_read_until_async()`, this function consumes the stop character that it finds.

Don't use this function in new code. Its functionality is inconsistent with `g_data_input_stream_read_until_async()`. Both functions will be marked as deprecated in a future release. Use `g_data_input_stream_read_upto()` instead, but note that that function does not consume the stop character.

#### Parameters

stream | a given GDataInputStream. |
stop_chars | characters to terminate the read. |
length | a gsize to get the length of the data read in. | [out]
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | GError for error reporting. |

#### Returns

a string with the data that was read before encountering any of the stop characters. Set `length` to a gsize to get the length of the string. This function will return `NULL` on an error.

[transfer full]

### g_data_input_stream_read_until_async ()

    void
    g_data_input_stream_read_until_async (GDataInputStream *stream,
                                          const gchar *stop_chars,
                                          gint io_priority,
                                          GCancellable *cancellable,
                                          GAsyncReadyCallback callback,
                                          gpointer user_data);

The asynchronous version of `g_data_input_stream_read_until()`. It is an error to have two outstanding calls to this function.

Note that, in contrast to `g_data_input_stream_read_until()`, this function does not consume the stop character that it finds. You must read it for yourself.

When the operation is finished, `callback` will be called. You can then call `g_data_input_stream_read_until_finish()` to get the result of the operation.

Don't use this function in new code. Its functionality is inconsistent with `g_data_input_stream_read_until()`. Both functions will be marked as deprecated in a future release. Use `g_data_input_stream_read_upto_async()` instead.

#### Parameters

stream | a given GDataInputStream. |
stop_chars | characters to terminate the read. |
io_priority | the I/O priority of the request |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
callback | callback to call when the request is satisfied. | [scope async]
user_data | the data to pass to callback function. | [closure]

Since: 2.20

### g_data_input_stream_read_until_finish ()

    char *
    g_data_input_stream_read_until_finish (GDataInputStream *stream,
                                           GAsyncResult *result,
                                           gsize *length,
                                           GError **error);

Finish an asynchronous call started by `g_data_input_stream_read_until_async()`.

#### Parameters

stream | a given GDataInputStream. |
result | the GAsyncResult that was provided to the callback. |
length | a gsize to get the length of the data read in. | [out]
error | GError for error reporting. |

#### Returns

a string with the data that was read before encountering any of the stop characters. Set `length` to a gsize to get the length of the string. This function will return `NULL` on an error.

[transfer full]

Since: 2.20

## Types and Values

### GDataInputStream

    typedef struct _GDataInputStream GDataInputStream;

An implementation of GBufferedInputStream that allows for high-level data manipulation of arbitrary data (including binary operations).

### enum GDataStreamByteOrder

GDataStreamByteOrder is used to ensure proper endianness of streaming data sources across various machine architectures.

#### Members

G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN | Selects Big Endian byte order. |
G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN | Selects Little Endian byte order. |
G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN | Selects endianness based on host machine's architecture. |

### enum GDataStreamNewlineType

GDataStreamNewlineType is used when checking for or setting the line endings for a given file.

#### Members

G_DATA_STREAM_NEWLINE_TYPE_LF | Selects "LF" line endings, common on most modern UNIX platforms. |
G_DATA_STREAM_NEWLINE_TYPE_CR | Selects "CR" line endings. |
G_DATA_STREAM_NEWLINE_TYPE_CR_LF | Selects "CR, LF" line ending, common on Microsoft Windows. |
G_DATA_STREAM_NEWLINE_TYPE_ANY | Automatically try to handle any line ending type. |

## Property Details

### The `“byte-order”` property

      “byte-order”               GDataStreamByteOrder

The byte order.

Flags: Read / Write

Default value: G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN

### The `“newline-type”` property

      “newline-type”             GDataStreamNewlineType

The accepted types of line ending.

Flags: Read / Write

Default value: G_DATA_STREAM_NEWLINE_TYPE_LF

## See Also

GInputStream