# IOChannel

## Name

IOChannel -- GIOChannel utility functions

## Synopsis

    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.