## IOChannel

IOChannel — GIOChannel utility functions

## Synopsis

    #include <gnet.h>

    GIOError            gnet_io_channel_writen              (GIOChannel *channel,
                                                             gpointer buffer,
                                                             gsize length,
                                                             gsize *bytes_writtenp);
    GIOError            gnet_io_channel_readn               (GIOChannel *channel,
                                                             gpointer buffer,
                                                             gsize length,
                                                             gsize *bytes_readp);
    GIOError            gnet_io_channel_readline            (GIOChannel *channel,
                                                             gchar *buffer,
                                                             gsize length,
                                                             gsize *bytes_readp);
    GIOError            gnet_io_channel_readline_strdup     (GIOChannel *channel,
                                                             gchar **bufferp,
                                                             gsize *bytes_readp);

## Description

The IOChannel module provides utility functions for reading from and writing to GIOChannels.

## Details

### gnet_io_channel_writen ()

    GIOError            gnet_io_channel_writen              (GIOChannel *channel,
                                                             gpointer buffer,
                                                             gsize length,
                                                             gsize *bytes_writtenp);

Writes all `length` bytes in `buffer` to `channel`. If `bytes_writtenp` is set, the number of bytes written is stored in the integer it points to. `bytes_writtenp` will be less than `length` if the connection closed or an error occured.

This function is essentially a wrapper around `g_io_channel_write()`. The problem with `g_io_channel_write()` is that it may not write all the bytes and will return a short count even when there was not an error. This is rare, but possible, and often difficult to detect when it does happen.

`channel` : | channel to write to
`buffer` : | buffer to read from
`length` : | length of `buffer`
`bytes_writtenp` : | pointer to integer in which to store the number of bytes written
Returns : | `G_IO_ERROR_NONE` if successful; something else otherwise. The number of bytes written is stored in the integer pointed to by `bytes_writtenp`.

### gnet_io_channel_readn ()

    GIOError            gnet_io_channel_readn               (GIOChannel *channel,
                                                             gpointer buffer,
                                                             gsize length,
                                                             gsize *bytes_readp);

Read exactly `length` bytes from `channel` into `buffer`. If `bytes_readp` is set, the number of bytes read is stored in the integer it points to. `bytes_readp` will be less than `length` if the end-of-file was reached or an error occured.

This function is essentially a wrapper around `g_io_channel_read()`. The problem with `g_io_channel_read()` is that it may not read all the bytes requested and will return a short count even when there was not an error (this is rare, but it can happen and is often difficult to detect when it does).

`channel` : | channel to read from
`buffer` : | buffer to write to
`length` : | length of the buffer
`bytes_readp` : | pointer to integer for the function to store the number of of bytes read
Returns : | `G_IO_ERROR_NONE` if everything is ok; something else otherwise. Also, returns the number of bytes read by modifying the integer pointed to by `bytes_readp`.

### gnet_io_channel_readline ()

    GIOError            gnet_io_channel_readline            (GIOChannel *channel,
                                                             gchar *buffer,
                                                             gsize length,
                                                             gsize *bytes_readp);

Read a line from the channel. The line will be NULL-terminated and include the newline character. If there is not enough room for the line, the line is truncated to fit in the buffer.

Warnings:

1. If the buffer is full and the last character is not a newline, the line was truncated. Do not assume the buffer ends with a newline.

2. `bytes_readp` is the number of bytes put in the buffer. It includes the terminating NULL character.

3. NULL characters can appear in the line before the terminating NULL (e.g., "Hello world\0\n"). If this matters, check the string length of the buffer against the bytes read.

I hope this isn't too confusing. Usually the function works as you expect it to if you have a big enough buffer. If you have the Stevens book, you should be familiar with the semantics.

`channel` : | channel to read from
`buffer` : | buffer to write to
`length` : | length of the buffer
`bytes_readp` : | pointer to integer in which to store the number of of bytes read
Returns : | `G_IO_ERROR_NONE` if everything is ok; something else otherwise. The number of bytes read is stored in the integer pointed to by `bytes_readp` (this number includes the newline). If an error is returned, the contents of `buffer` and `bytes_readp` are undefined.

### gnet_io_channel_readline_strdup ()

    GIOError            gnet_io_channel_readline_strdup     (GIOChannel *channel,
                                                             gchar **bufferp,
                                                             gsize *bytes_readp);

Read a line from the channel. The line will be null-terminated and include the newline character. Similarly to g_strdup_printf, a buffer large enough to hold the string will be allocated.

Warnings:

1. If the last character of the buffer is not a newline, the line was truncated by EOF. Do not assume the buffer ends with a newline.

2. `bytes_readp` is actually the number of bytes put in the buffer. It includes the terminating NULL character.

3. NULL characters can appear in the line before the terminating null (e.g., "Hello world\0\n"). If this matters, check the string length of the buffer against the bytes read.

`channel` : | channel to read from
`bufferp` : | pointer to gchar* in which to store the new buffer
`bytes_readp` : | pointer to integer in which to store the number of of bytes read
Returns : | `G_IO_ERROR_NONE` if everything is ok; something else otherwise. The number of bytes read is stored in the integer pointed to by `bytes_readp` (this number includes the newline). The data pointer is stored in the pointer pointed to by `bufferp`. This data is caller-owned. If an error is returned, the contents of `bufferp` and `bytes_readp` are undefined.