prelude-io: libprelude Reference Manual

## prelude-io prelude-io |

## Functions

int | prelude_io_new ()
void | prelude_io_destroy ()
void | prelude_io_set_file_io ()
void | prelude_io_set_tls_io ()
void | prelude_io_set_sys_io ()
int | prelude_io_set_buffer_io ()
void | prelude_io_set_fdptr ()
void | prelude_io_set_pending_callback ()
void | prelude_io_set_read_callback ()
void | prelude_io_set_write_callback ()
int | prelude_io_close ()
ssize_t | prelude_io_read ()
ssize_t | prelude_io_read_wait ()
ssize_t | prelude_io_read_delimited ()
ssize_t | prelude_io_write ()
ssize_t | prelude_io_write_delimited ()
ssize_t | prelude_io_forward ()
int | prelude_io_get_fd ()
void * | prelude_io_get_fdptr ()
ssize_t | prelude_io_pending ()
prelude_bool_t | prelude_io_is_error_fatal ()

## Types and Values

typedef | prelude_io_t

## Description

## Functions

### prelude_io_new ()

    int
    prelude_io_new (prelude_io_t **ret);

Create a new prelude IO object.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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);

### 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()`.

#### Parameters

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 (*pending) (prelude_io_t *io));

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

#### Parameters

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 (*read) (prelude_io_t *io, void *buf, size_t count));

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

#### Parameters

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 (*write) (prelude_io_t *io, const void *buf, size_t count));

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

src | Pointer to a prelude_io_t object. |
dst | 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);

#### Parameters

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);

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

## Types and Values

### prelude_io_t

    typedef struct prelude_io prelude_io_t;