## prelude-io

prelude-io

## Synopsis

    typedef             prelude_io_t;
    int                 prelude_io_new                      (prelude_io_t **ret);
    void                prelude_io_destroy                  (prelude_io_t *pio);
    void                prelude_io_set_file_io              (prelude_io_t *pio,
                                                             FILE *fd);
    void                prelude_io_set_tls_io               (prelude_io_t *pio,
                                                             void *tls);
    void                prelude_io_set_sys_io               (prelude_io_t *pio,
                                                             int fd);
    int                 prelude_io_set_buffer_io            (prelude_io_t *pio);
    void                prelude_io_set_fdptr                (prelude_io_t *pio,
                                                             void *ptr);
    void                prelude_io_set_pending_callback     (prelude_io_t *pio,
                                                             ssize_t (pendingprelude_io_t *io) ());
    void                prelude_io_set_read_callback        (prelude_io_t *pio,
                                                             ssize_t (readprelude_io_t *io, void *buf, size_t count) ());
    void                prelude_io_set_write_callback       (prelude_io_t *pio,
                                                             ssize_t (writeprelude_io_t *io, const void *buf, size_t count) ());
    int                 prelude_io_close                    (prelude_io_t *pio);
    ssize_t             prelude_io_read                     (prelude_io_t *pio,
                                                             void *buf,
                                                             size_t count);
    ssize_t             prelude_io_read_wait                (prelude_io_t *pio,
                                                             void *buf,
                                                             size_t count);
    ssize_t             prelude_io_read_delimited           (prelude_io_t *pio,
                                                             unsigned char **buf);
    ssize_t             prelude_io_write                    (prelude_io_t *pio,
                                                             const void *buf,
                                                             size_t count);
    ssize_t             prelude_io_write_delimited          (prelude_io_t *pio,
                                                             const void *buf,
                                                             uint16_t count);
    ssize_t             prelude_io_forward                  (prelude_io_t *dst,
                                                             prelude_io_t *src,
                                                             size_t count);
    int                 prelude_io_get_fd                   (prelude_io_t *pio);
    void *              prelude_io_get_fdptr                (prelude_io_t *pio);
    ssize_t             prelude_io_pending                  (prelude_io_t *pio);
    prelude_bool_t      prelude_io_is_error_fatal           (prelude_io_t *pio,
                                                             int error);

## Description

## Details

### prelude_io_t

    typedef struct prelude_io prelude_io_t;

### prelude_io_new ()

    int                 prelude_io_new                      (prelude_io_t **ret);

Create a new prelude IO object.

`ret` : | Pointer where to store the created prelude_io_t object.
Returns : | 0 on success, or a negative value if an error occur.

### prelude_io_destroy ()

    void                prelude_io_destroy                  (prelude_io_t *pio);

Destroy the `pio` object.

`pio` : | Pointer to a prelude_io_t object.

### prelude_io_set_file_io ()

    void                prelude_io_set_file_io              (prelude_io_t *pio,
                                                             FILE *fd);

Setup the `pio` object to work with file I/O function. The `pio` object is then associated with `fd`.

`pio` : | A pointer on the prelude_io_t object.
`fd` : | File descriptor identifying a file.

### prelude_io_set_tls_io ()

    void                prelude_io_set_tls_io               (prelude_io_t *pio,
                                                             void *tls);

Setup the `pio` object to work with TLS based I/O function. The `pio` object is then associated with `tls`.

`pio` : | A pointer on the prelude_io_t object.
`tls` : | Pointer on the TLS structure holding the TLS connection data.

### prelude_io_set_sys_io ()

    void                prelude_io_set_sys_io               (prelude_io_t *pio,
                                                             int fd);

Setup the `pio` object to work with system based I/O function. The `pio` object is then associated with `fd`.

`pio` : | A pointer on the prelude_io_t object.
`fd` : | A file descriptor.

### prelude_io_set_buffer_io ()

    int                 prelude_io_set_buffer_io            (prelude_io_t *pio);

`pio` : |
Returns : |

### prelude_io_set_fdptr ()

    void                prelude_io_set_fdptr                (prelude_io_t *pio,
                                                             void *ptr);

Set an user defined pointer that might be retrieved using `prelude_io_get_fdptr()`.

`pio` : | Pointer to a prelude_io_t object.
`ptr` : | Pointer to user defined data.

### prelude_io_set_pending_callback ()

    void                prelude_io_set_pending_callback     (prelude_io_t *pio,
                                                             ssize_t (pendingprelude_io_t *io) ());

Set an user defined read callback function to be called on `prelude_io_pending()`.

`pio` : | Pointer to a prelude_io_t object.
`pending` : | Callback function to be called on `prelude_io_pending()`.

### prelude_io_set_read_callback ()

    void                prelude_io_set_read_callback        (prelude_io_t *pio,
                                                             ssize_t (readprelude_io_t *io, void *buf, size_t count) ());

Set an user defined read callback function to be called on `prelude_io_read()`.

`pio` : | Pointer to a prelude_io_t object.
`read` : | Callback function to be called on `prelude_io_read()`.

### prelude_io_set_write_callback ()

    void                prelude_io_set_write_callback       (prelude_io_t *pio,
                                                             ssize_t (writeprelude_io_t *io, const void *buf, size_t count) ());

Set an user defined write callback function to be called on `prelude_io_write()`.

`pio` : | Pointer to a prelude_io_t object.
`write` : | Callback function to be called on `prelude_io_write()`.

### prelude_io_close ()

    int                 prelude_io_close                    (prelude_io_t *pio);

`prelude_io_close()` closes the file descriptor indentified by `pio`,

The case where the `close()` function would be interrupted by a signal is handled internally. So you don't have to check for EINTR.

However, and especially when the underlaying layer is TLS, `prelude_io_close()` might return error. If this happen, you should continue calling the function until it return zero.

`pio` : | Pointer to a prelude_io_t object.
Returns : | zero on success, or -1 if an error occurred.

### prelude_io_read ()

    ssize_t             prelude_io_read                     (prelude_io_t *pio,
                                                             void *buf,
                                                             size_t count);

`prelude_io_read()` attempts to read up to `count` bytes from the file descriptor identified by `pio` into the buffer starting at `buf`.

If `count` is zero, `prelude_io_read()` returns zero and has no other results. If `count` is greater than SSIZE_MAX, the result is unspecified.

The case where the read function would be interrupted by a signal is handled internally. So you don't have to check for EINTR.

`pio` : | Pointer to a prelude_io_t object.
`buf` : | Pointer to the buffer to store data into.
`count` : | Number of bytes to read.

Returns :

On success, the number of bytes read is returned (zero indicates end of file). It is not an error if this number is smaller than the number of bytes requested; this may happen for example because fewer bytes are actually available right now or because `read()` was interrupted by a signal. On error, a negative value is returned. In this case it is left unspecified whether the file position (if any) changes.

### prelude_io_read_wait ()

    ssize_t             prelude_io_read_wait                (prelude_io_t *pio,
                                                             void *buf,
                                                             size_t count);

`prelude_io_read_wait()` attempts to read up to `count` bytes from the file descriptor identified by `pio` into the buffer starting at `buf`.

If `count` is zero, `prelude_io_read()` returns zero and has no other results. If `count` is greater than SSIZE_MAX, the result is unspecified.

The case where the read function would be interrupted by a signal is handled internally. So you don't have to check for EINTR.

`prelude_io_read_wait()` always return the number of bytes requested. Be carefull that this function is blocking.

`pio` : | Pointer to a prelude_io_t object.
`buf` : | Pointer to the buffer to store data into.
`count` : | Number of bytes to read.
Returns : | On success, the number of bytes read is returned (zero indicates end of file). On error, -1 is returned, and errno is set appropriately. In this case it is left unspecified whether the file position (if any) changes.

### prelude_io_read_delimited ()

    ssize_t             prelude_io_read_delimited           (prelude_io_t *pio,
                                                             unsigned char **buf);

`prelude_io_read_delimited()` read message written by `prelude_write_delimited()`. Theses messages are sents along with the len of the message.

Uppon return the `buf` argument is updated to point on a newly allocated buffer containing the data read. The `count` argument is set to the number of bytes the message was containing.

The case where the read function would be interrupted by a signal is handled internally. So you don't have to check for EINTR.

`pio` : | Pointer to a prelude_io_t object.
`buf` : | Pointer to the address of a buffer to store address of data into.
Returns : | On success, the number of bytes read is returned (zero indicates end of file). On error, -1 is returned, and errno is set appropriately. In this case it is left unspecified whether the file position (if any) changes.

### prelude_io_write ()

    ssize_t             prelude_io_write                    (prelude_io_t *pio,
                                                             const void *buf,
                                                             size_t count);

`prelude_io_write()` writes up to `count` bytes to the file descriptor identified by `pio` from the buffer starting at `buf`. POSIX requires that a `read()` which can be proved to occur after a `write()` has returned returns the new data. Note that not all file systems are POSIX conforming.

The case where the `write()` function would be interrupted by a signal is handled internally. So you don't have to check for EINTR.

`pio` : | Pointer to a prelude_io_t object.
`buf` : | Pointer to the buffer to write data from.
`count` : | Number of bytes to write.
Returns : | On success, the number of bytes written are returned (zero indicates nothing was written). On error, -1 is returned, and errno is set appropriately. If `count` is zero and the file descriptor refers to a regular file, 0 will be returned without causing any other effect. For a special file, the results are not portable.

### prelude_io_write_delimited ()

    ssize_t             prelude_io_write_delimited          (prelude_io_t *pio,
                                                             const void *buf,
                                                             uint16_t count);

`prelude_io_write_delimited()` writes up to `count` bytes to the file descriptor identified by `pio` from the buffer starting at `buf`. POSIX requires that a `read()` which can be proved to occur after a `write()` has returned returns the new data. Note that not all file systems are POSIX conforming.

`prelude_io_write_delimited()` also write the len of the data to be sent. which allow `prelude_io_read_delimited()` to safely know if it got all the data a given write contain.

The case where the `write()` function would be interrupted by a signal is handled internally. So you don't have to check for EINTR.

`pio` : | Pointer to a prelude_io_t object.
`buf` : | Pointer to the buffer to write data from.
`count` : | Number of bytes to write.
Returns : | On success, the number of bytes written are returned (zero indicates nothing was written). On error, -1 is returned, and errno is set appropriately.

### prelude_io_forward ()

    ssize_t             prelude_io_forward                  (prelude_io_t *dst,
                                                             prelude_io_t *src,
                                                             size_t count);

`prelude_io_forward()` attempts to transfer up to `count` bytes from the file descriptor identified by `src` into the file descriptor identified by `dst`.

`dst` : | Pointer to a prelude_io_t object.
`src` : | Pointer to a prelude_io_t object.
`count` : | Number of byte to forward from `src` to `dst`.
Returns : | If the transfer was successful, the number of bytes written to `dst` is returned. On error, -1 is returned, and errno is set appropriately.

### prelude_io_get_fd ()

    int                 prelude_io_get_fd                   (prelude_io_t *pio);

`pio` : | A pointer on a prelude_io_t object.
Returns : | The FD associated with this object.

### prelude_io_get_fdptr ()

    void *              prelude_io_get_fdptr                (prelude_io_t *pio);

`pio` : | A pointer on a prelude_io_t object.
Returns : | Pointer associated with this object (file, tls, buffer, or NULL).

### prelude_io_pending ()

    ssize_t             prelude_io_pending                  (prelude_io_t *pio);

prelude_io_pending return the number of bytes waiting to be read on an TLS or socket fd.

`pio` : | Pointer to a prelude_io_t object.
Returns : | Number of byte waiting to be read on `pio`, or -1 if `pio` is not of type TLS or socket.

### prelude_io_is_error_fatal ()

    prelude_bool_t      prelude_io_is_error_fatal           (prelude_io_t *pio,
                                                             int error);

Check whether the returned error is fatal, or not.

`pio` : | Pointer to a prelude_io_t object.
`error` : | Error returned by one of the prelude_io_t function.
Returns : | TRUE if error is fatal, FALSE if it is not.