## 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);
    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_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.