prelude-io

prelude-io

Functions

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;